Importer et exporter des données à l’aide de l’extension azure_storage dans Azure Database pour PostgreSQL - Serveur flexible

Article
11/19/2024

S’APPLIQUE À : Azure Database pour PostgreSQL : serveur flexible

L’extension azure_storage vous permet d’importer ou d’exporter des données dans plusieurs formats de fichiers, directement entre Stockage Azure comptes et une instance de serveur flexible Azure Database pour PostgreSQL.

Vous trouverez des exemples d’exportation et d’importation de données à l’aide de cette extension dans la section Exemples de cet article.

Pour utiliser l’extension azure_storage sur votre instance de serveur flexible Azure Database pour PostgreSQL, vous devez ajouter l’extension au shared_preload_librariesparamètre de serveur, et l’ajouter au paramètre de azure.extensions serveur, comme décrit dans la procédure d’utilisation des extensions PostgreSQL.

Étant donné qu’il shared_preload_library s’agit d’un paramètre de serveur statique, il nécessite un redémarrage du serveur pour que la modification prenne effet.

Une fois le serveur redémarré, connectez-vous à votre instance de PostgreSQL à l’aide du client de votre préférence (par exemple psql, pgAdmin, etc.). Vérifiez que SHOW azure.extensions;, et SHOW shared_preload_libraries;, les deux incluent la valeur azure_storage dans la liste des valeurs séparées par des virgules retournées par chacune des SHOW instructions.

Vous pouvez uniquement installer l’extension, en vous connectant à votre base de données cible et en exécutant l’instruction CREATE EXTENSION . Vous devez répéter la commande séparément pour chaque base de données dans laquelle vous souhaitez que l’extension soit disponible.

CREATE EXTENSION azure_storage;

Vue d’ensemble de la procédure

Identifiez les comptes Stockage Azure avec lesquels vous souhaitez que les utilisateurs de l’extension azure_storage interagissent.
Déterminez le type d’autorisation que vous souhaitez utiliser pour les demandes effectuées sur le service blob de chacun de ces comptes Stockage Azure. azure_storage l’extension prend en charge l’autorisation avec la clé partagée et l’autorisation avec l’ID Microsoft Entra. Parmi ces deux types d’autorisation, Microsoft Entra ID offre une sécurité et une facilité d’utilisation supérieures sur la clé partagée, et est celui que Microsoft recommande. Pour répondre aux conditions préalables requises dans chaque cas, suivez les instructions des sections correspondantes :
- Autorisation avec l’ID Microsoft Entra ou
- Autorisation avec Clé partagée.
Inclure azure_storage dans shared_preload_libraries:

Étant donné que l’élément shared_preload_libraries est statique, le serveur doit être redémarré pour qu’une modification prenne effet :

az postgres flexible-server parameter set --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name shared_preload_libraries --source user-override --value azure_storage,$(az postgres flexible-server parameter show --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name shared_preload_libraries --query value --output tsv)

Étant donné que l’élément shared_preload_libraries est statique, le serveur doit être redémarré pour qu’une modification prenne effet :

az postgres flexible-server restart --resource-group <flexible_server_resource_group> --name <flexible_server_name>

Inclure azure_storage dans azure.extensions:

az postgres flexible-server parameter set --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name azure.extensions --source user-override --value azure_storage,$(az postgres flexible-server parameter show --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name azure.extensions --query value --output tsv)

À l’aide du client de votre préférence (par exemple, psql, pgAdmin, etc.), connectez-vous à n’importe quelle base de données dans votre instance de Azure Database pour PostgreSQL serveur flexible. Pour créer tous les objets SQL (tables, types, fonctions, vues, etc.) avec lesquels vous pouvez utiliser l’extension azure_storage pour interagir avec des instances de comptes Stockage Azure, exécutez l’instruction suivante :
```
CREATE EXTENSION azure_storage;
```
À l’aide des azure_storage.account_* fonctions, ajoutez des références à Stockage Azure comptes que vous souhaitez autoriser les utilisateurs ou les rôles PostgreSQL à accéder à l’extensionazure_storage. Ces références incluent le nom du compte Stockage Azure référencé et le type d’authentification à utiliser lors de l’interaction avec le compte Stockage Azure. Selon le type d’authentification sélectionné, vous devrez peut-être également fournir d’autres paramètres, tels que la clé d’accès au compte Stockage Azure ou le jeton SAP.

Important

Pour les types d’authentification pour lesquels vous devez fournir une clé d’accès de compte Stockage Azure, notez que vos clés d’accès Stockage Azure sont similaires à un mot de passe racine pour votre compte de stockage. Veillez toujours à les protéger. Utilisez Azure Key Vault pour gérer et effectuer la rotation de vos clés en toute sécurité. azure_storage l’extension stocke ces clés dans une table azure_storage.accounts qui peut être lue par les membres du pg_read_all_data rôle.

Les utilisateurs disposant du azure_storage_admin rôle peuvent interagir avec la azure_storage.accounts table à l’aide des fonctions suivantes :

azure_storage.account_add
azure_storage.account_list
azure_storage.account_remove
azure_storage.account_user_add
azure_storage.account_user_remove

Le azure_storage_admin rôle est, par défaut, accordé au azure_pg_admin rôle.

Pour utiliser l’autorisation avec l’ID Microsoft Entra

Activez l’identité managée affectée par le système sur votre instance de Azure Database pour PostgreSQL serveur flexible.

az rest --method patch --url https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<flexible_server_resource_group>/providers/Microsoft.DBforPostgreSQL/flexibleServers/<flexible_server_name>?api-version=2024-08-01 --body '{"identity":{"type":"SystemAssigned"}}'

Redémarrez l’instance de Azure Database pour PostgreSQL serveur flexible, après avoir activé une identité managée affectée par le système.
Attribuez des autorisations de contrôle d’accès en fonction du rôle (RBAC) pour l’accès aux données blob, sur le compte Stockage Azure, à l’identité managée affectée par le système de votre instance de Azure Database pour PostgreSQL serveur flexible.

Pour utiliser l’autorisation avec la clé partagée

Votre compte Stockage Azure doit avoir activé l’accès à la clé de compte de stockage (autrement dit, sa propriété AllowSharedKeyAccess n’est pas définie sur false).

az storage account update --resource-group <storage_account_resource_group> --name <storage_account> --allow-shared-key-access true

Pour le transmettre à la fonction azure_storage.account_add, récupérez l’une des deux clés d’accès du compte Stockage Azure.

az storage account keys list --resource-group <storage_account_resource_group> --account-name <storage_account> --query [0].value -o tsv

Functions

azure_storage.account_add

Fonction qui permet d’ajouter un compte de stockage et sa clé d’accès associée à la liste des comptes de stockage auxquels l’extension azure_storage peut accéder.

Si un appel précédent de cette fonction a déjà ajouté la référence à ce compte de stockage, il n’ajoute pas de nouvelle entrée, mais met à jour plutôt la clé d’accès de l’entrée existante.

Remarque

Cette fonction ne valide pas si le nom du compte référencé existe ou s’il est accessible avec la clé d’accès fournie. Toutefois, il vérifie que le nom du compte de stockage est valide, conformément aux règles de validation de nommage imposées sur les comptes de stockage Azure.

azure_storage.account_add(account_name_p text, account_key_p text);

Il existe une version surchargée de cette fonction, qui accepte un account_config paramètre qui encapsule le nom du compte Stockage Azure référencé, ainsi que tous les paramètres requis tels que le type d’authentification, le type de compte ou les informations d’identification de stockage.

azure_storage.account_add(account_config jsonb);

autorisations

Doit être membre de azure_storage_admin.

Arguments

account_name_p

text nom du compte de stockage d’objets blob Azure qui contient tous vos objets : objets blob, fichiers, files d’attente et tables. Le compte de stockage fournit un espace de noms unique accessible n’importe où dans le monde via HTTPS.

account_key_p

text valeur de l’une des clés d’accès pour le compte de stockage. Vos clés d’accès au stockage Blob Azure sont similaires à un mot de passe racine pour votre compte de stockage. Veillez toujours à protéger vos clés d’accès. Utilisez Azure Key Vault pour gérer et effectuer la rotation de vos clés en toute sécurité. La clé de compte est stockée dans une table accessible uniquement par le superutilisateur. Les utilisateurs disposant du azure_storage_admin rôle peuvent interagir avec cette table via des fonctions. Pour voir quels comptes de stockage sont ajoutés, utilisez la fonction azure_storage.account_list.

account_config

jsonble nom du compte Stockage Azure et tous les paramètres requis, tels que le type d’authentification, le type de compte ou les informations d’identification de stockage. Nous vous recommandons d’utiliser les fonctions utilitaires azure_storage.account_options_managed_identity, azure_storage.account_options_credentials ou azure_storage.account_options pour créer les valeurs valides qui doivent être passées en tant qu’argument.

Type renvoyé

VOID

azure_storage.account_options_managed_identity

Fonction qui agit comme une fonction utilitaire, qui peut être appelée en tant que paramètre dans azure_storage.account_add, et est utile pour produire une valeur valide pour l’argument, lors de l’utilisation account_config d’une identité managée affectée par le système pour interagir avec le compte Stockage Azure.

azure_storage.account_options_managed_identity(name text, type azure_storage.storage_type);

autorisations

Tout utilisateur ou rôle peut appeler cette fonction.

Arguments

name

type

azure_storage.storage_type valeur de l’un des types de stockage pris en charge. Seule la valeur prise en charge est blob.

Type renvoyé

jsonb

azure_storage.account_options_credentials

Fonction qui agit comme une fonction utilitaire, qui peut être appelée en tant que paramètre dans azure_storage.account_add, et est utile pour produire une valeur valide pour l’argument, lors de l’utilisation account_config d’une clé d’accès Stockage Azure pour interagir avec le compte Stockage Azure.

azure_storage.account_options_credentials(name text, credentials text, type azure_storage.storage_type);

autorisations

Tout utilisateur ou rôle peut appeler cette fonction.

Arguments

name

credentials

type

azure_storage.storage_type valeur de l’un des types de stockage pris en charge. Seule la valeur prise en charge est blob.

Type renvoyé

jsonb

azure_storage.account_options

Fonction qui agit comme une fonction utilitaire, qui peut être appelée en tant que paramètre dans azure_storage.account_add, et est utile pour produire une valeur valide pour l’argument, lors de l’utilisation account_config d’une clé d’accès Stockage Azure ou d’une identité managée affectée par le système pour interagir avec le compte Stockage Azure.

azure_storage.account_options(name text, auth_type azure_storage.auth_type, storage_type azure_storage.storage_type, credentials text DEFAULT NULL);

autorisations

Tout utilisateur ou rôle peut appeler cette fonction.

Arguments

name

auth_type

azure_storage.auth_type valeur de l’un des types de stockage pris en charge. Seules les valeurs prises en charge sont access-key, et managed-identity.

storage_type

azure_storage.storage_type valeur de l’un des types de stockage pris en charge. Seule la valeur prise en charge est blob.

credentials

Type renvoyé

jsonb

azure_storage.account_remove

Fonction qui permet de supprimer un compte de stockage et sa clé d’accès associée dans la liste des comptes de stockage auxquels l’extension azure_storage peut accéder.

azure_storage.account_remove(account_name_p text);

autorisations

Doit être membre de azure_storage_admin.

Arguments

account_name_p

Type renvoyé

VOID

azure_storage.account_user_add

Fonction qui permet d’accorder à un utilisateur ou un rôle PostgreSQL l’accès à un compte de stockage via les fonctions fournies par l’extension azure_storage .

Remarque

L’exécution de cette fonction réussit uniquement si le compte de stockage, dont le nom est passé en tant que premier argument, a déjà été créé à l’aide de azure_storage.account_add, et si l’utilisateur ou le rôle, dont le nom est passé en tant que deuxième argument, existe déjà.

azure_storage.account_add(account_name_p text, user_p regrole);

autorisations

Doit être membre de azure_storage_admin.

Arguments

account_name_p

user_p

regrole nom d’un utilisateur ou d’un rôle PostgreSQL disponible sur le serveur.

Type renvoyé

VOID

azure_storage.account_user_remove

Fonction qui permet de révoquer un utilisateur ou un rôle PostgreSQL d’accéder à un compte de stockage via les fonctions fournies par l’extension azure_storage .

Remarque

L’exécution de cette fonction réussit uniquement si le compte de stockage dont le nom est passé en tant que premier argument a déjà été créé à l’aide de azure_storage.account_add, et si l’utilisateur ou le rôle dont le nom est passé en tant que deuxième argument existe toujours. Lorsqu’un utilisateur ou un rôle est supprimé du serveur, en exécutant DROP USER | ROLE, les autorisations accordées sur n’importe quelle référence aux comptes Stockage Azure sont également supprimées automatiquement.

azure_storage.account_user_remove(account_name_p text, user_p regrole);

autorisations

Doit être membre de azure_storage_admin.

Arguments

account_name_p

user_p

regrole nom d’un utilisateur ou d’un rôle PostgreSQL disponible sur le serveur.

Type renvoyé

VOID

azure_storage.account_list

Fonction qui répertorie les noms des comptes de stockage qui ont été configurés via la fonction azure_storage.account_add , ainsi que les utilisateurs ou rôles PostgreSQL qui disposent des autorisations d’interaction avec ce compte de stockage via les fonctions fournies par l’extension azure_storage .

azure_storage.account_list();

autorisations

Doit être membre de azure_storage_admin.

Arguments

Cette fonction ne prend aucun argument.

Type renvoyé

TABLE(account_name text, auth_type azure_storage.auth_type, azure_storage_type azure_storage.storage_type, allowed_users regrole[])Une table à quatre colonnes avec la liste des comptes d’Stockage Azure ajoutés, le type d’authentification utilisé pour interagir avec chaque compte, le type de stockage et la liste des utilisateurs ou rôles PostgreSQL auxquels l’accès est accordé.

azure_storage.blob_list

Fonction qui répertorie les noms et autres propriétés (taille, lastModified, eTag, contentType, contentEncoding et contentHash) des objets blob stockés dans le conteneur donné du compte de stockage référencé.

azure_storage.blob_list(account_name text, container_name text, prefix text DEFAULT ''::text);

autorisations

L’utilisateur ou le rôle appelant cette fonction doit être ajouté à la liste autorisée pour l’utilisateur ou le account_name rôle référencé, en exécutant azure_storage.account_user_add. Les membres sont azure_storage_admin automatiquement autorisés à référencer tous les comptes Stockage Azure dont les références ont été ajoutées à l’aide de azure_storage.account_add.

Arguments

account_name

container_name

text nom d’un conteneur. Un conteneur regroupe un ensemble d’objets blob, à la manière d’un répertoire dans un système de fichiers. Un compte de stockage peut contenir un nombre illimité de conteneurs, et un conteneur peut stocker un nombre illimité d’objets blob. Un nom de conteneur doit être un nom DNS (Domain Name System) valide, car il fait partie de l’URI unique utilisé pour traiter le conteneur ou ses objets blob. Lorsque vous nommez un conteneur, veillez à suivre ces règles.

L’URI d’un conteneur est similaire à : https://myaccount.blob.core.windows.net/mycontainer

prefix

text lorsqu’elle est spécifiée, la fonction retourne les objets blob dont les noms commencent par la valeur fournie dans ce paramètre. La valeur par défaut est une chaîne vide.

Type renvoyé

TABLE(path text, bytes bigint, last_modified timestamp with time zone, etag text, content_type text, content_encoding text, content_hash text) une table avec un enregistrement par objet blob retourné, y compris le nom complet de l’objet blob et d’autres propriétés.

path

text nom complet de l’objet blob.

octets

bigint taille de l’objet blob en octets.

last_modified

timestamp with time zonedate et heure de la dernière modification de l’objet blob. Toute opération qui modifie l’objet blob, notamment une mise à jour des métadonnées ou des propriétés de l’objet blob, modifie l’heure de la dernière modification de l’objet blob.

etag

text la propriété ETag est utilisée pour l’accès concurrentiel optimiste pendant les mises à jour. Il ne s’agit pas d’un timestamp, car il existe une autre propriété appelée Timestamp qui stocke la dernière fois qu’un enregistrement a été mis à jour. Par exemple, si vous chargez une entité et que vous souhaitez la mettre à jour, l’ETag doit correspondre à ce qui est actuellement stocké. Il est important de définir l’ETag approprié, car si plusieurs utilisateurs modifient le même élément, vous ne souhaitez pas qu’ils remplacent les modifications des autres utilisateurs.

content_type

text type de contenu spécifié pour l’objet blob. Le type de contenu par défaut est application/octet-stream.

content_encoding

textla propriété Content-Encoding d’un objet blob qui Stockage Azure vous permet de définir. Pour le contenu compressé, vous pouvez définir la propriété sur Gzip. Lorsque le navigateur accède au contenu, il désactive automatiquement le contenu.

content_hash

text hachage utilisé pour vérifier l’intégrité de l’objet blob pendant le transport. Lorsque cet en-tête est spécifié, le service de stockage vérifie le hachage fourni avec un contenu calculé. Si les deux hachages ne correspondent pas, l'opération échoue avec le code d'erreur 400 (Demande incorrecte).

azure_storage.blob_get

Fonction qui permet l’importation de données. Il télécharge un ou plusieurs fichiers à partir d’un conteneur d’objets blob dans un compte Stockage Azure. Ensuite, il traduit le contenu en lignes, qui peut être consommé et traité avec des constructions de langage SQL. Cette fonction ajoute la prise en charge du filtrage et de la manipulation des données extraites du conteneur d’objets blob avant de l’importer.

Remarque

Avant d’essayer d’accéder au conteneur pour le compte de stockage référencé, cette fonction vérifie si les noms du compte de stockage et du conteneur transmis en tant qu’arguments sont valides en fonction des règles de validation d’affectation de noms imposées sur les comptes de stockage Azure. Si l’un d’eux n’est pas valide, une erreur est générée.

azure_storage.blob_get(account_name text, container_name text, path text, decoder text DEFAULT 'auto'::text, compression text DEFAULT 'auto'::text, options jsonb DEFAULT NULL::jsonb);

Il existe une version surchargée de cette fonction, qui accepte un rec paramètre qui vous permet de définir facilement l’enregistrement de format de sortie.

azure_storage.blob_get(account_name text, container_name text, path text, rec anyelement, decoder text DEFAULT 'auto'::text, compression text DEFAULT 'auto'::text, options jsonb DEFAULT NULL::jsonb);

autorisations

Arguments

account_name

container_name

L’URI d’un conteneur est similaire à : https://myaccount.blob.core.windows.net/mycontainer

path

text nom complet de l’objet blob.

rec

anyelement définition de la structure de sortie d’enregistrement.

decoder

text spécification du format d’objet blob. Peut être défini sur l’une des valeurs suivantes :

Format	Par défaut	Description
`auto`	`true`	Déduit la valeur en fonction de la dernière série de caractères attribués au nom de l’objet blob. Si le nom de l’objet blob se termine `.csv` par ou `.csv.gz`, il suppose `csv`. Si elle se termine par `.tsv` ou `.tsv.gz`, elle part du principe `tsv`. Si se termine par `.json`, , `.xml.json.gz`, `.xml.gz`, `.txt`ou `.txt.gz`, il suppose `text`.
`csv`		Format de valeurs séparées par des virgules utilisées par PostgreSQL COPY.
`tsv`		Valeurs séparées par des onglets, format PostgreSQL COPY par défaut.
`binary`		Format COPY PostgreSQL binaire.
`text` \| `xml` \| `json`		Fichier contenant une valeur de texte unique.

compression

text spécification du type de compression. Peut être défini sur l’une des valeurs suivantes :

Format	Par défaut	Description
`auto`	`true`	Déduit la valeur en fonction de la dernière série de caractères attribués au nom de l’objet blob. Si le nom de l’objet blob se termine `.gz`par , il suppose `gzip`. Sinon, il suppose `none`.
`gzip`		Force l’utilisation du décodeur gzip pour décompresser l’objet blob.
`none`		Force à traiter l’objet blob comme un objet blob qui ne nécessite pas de décompression.

L’extension ne prend pas en charge d’autres types de compression.

options

jsonb les paramètres qui définissent la gestion des en-têtes personnalisés, des séparateurs personnalisés, des caractères d’échappement, etc. options affecte le comportement de cette fonction d’une manière similaire à la façon dont les options que vous pouvez transmettre à la COPY commande dans PostgreSQL affectent son comportement.

Type renvoyé

SETOF record SETOF anyelement

azure_storage.blob_put

Fonction qui permet d’exporter des données, en chargeant des fichiers dans un conteneur d’objets blob dans un compte Stockage Azure. Le contenu des fichiers est généré à partir de lignes dans PostgreSQL.

Remarque

azure_storage.blob_put(account_name text, container_name text, path text, tuple record)
RETURNS VOID;

Il existe une version surchargée de la fonction, contenant encoder un paramètre qui vous permet de spécifier l’encodeur à utiliser lorsqu’il ne peut pas être déduit à partir de l’extension du path paramètre, ou lorsque vous souhaitez remplacer celui déduit.

azure_storage.blob_put(account_name text, container_name text, path text, tuple record, encoder text)
RETURNS VOID;

Il existe une version surchargée de la fonction qui contient également un compression paramètre qui vous permet de spécifier la compression à utiliser lorsqu’elle ne peut pas être déduite à partir de l’extension path du paramètre, ou lorsque vous souhaitez remplacer celle déduite.

azure_storage.blob_put(account_name text, container_name text, path text, tuple record, encoder text, compression text)
RETURNS VOID;

Il existe une version surchargée de fonction qui contient également un options paramètre pour la gestion des en-têtes personnalisés, des séparateurs personnalisés, des caractères d’échappement, etc. options fonctionne de la même manière que les options qui peuvent être passées à la COPY commande dans PostgreSQL.

azure_storage.blob_put(account_name text, container_name text, path text, tuple record, encoder text, compression text, options jsonb)
RETURNS VOID;

autorisations

Arguments

account_name

container_name

L’URI d’un conteneur est similaire à : https://myaccount.blob.core.windows.net/mycontainer

path

text nom complet de l’objet blob.

tuple

record définition de la structure de sortie d’enregistrement.

codeur

text spécification du format d’objet blob. Peut être défini sur l’une des valeurs suivantes :

Format	Par défaut	Description
`auto`	`true`	Déduit la valeur en fonction de la dernière série de caractères attribués au nom de l’objet blob. Si le nom de l’objet blob se termine `.csv` par ou `.csv.gz`, il suppose `csv`. Si elle se termine par `.tsv` ou `.tsv.gz`, elle part du principe `tsv`. Si se termine par `.json`, , `.xml.json.gz`, `.xml.gz`, `.txt`ou `.txt.gz`, il suppose `text`.
`csv`		Format de valeurs séparées par des virgules utilisées par PostgreSQL COPY.
`tsv`		Valeurs séparées par des onglets, format PostgreSQL COPY par défaut.
`binary`		Format COPY PostgreSQL binaire.
`text` \| `xml` \| `json`		Fichier contenant une valeur de texte unique.

compression

text spécification du type de compression. Peut être défini sur l’une des valeurs suivantes :

Format	Par défaut	Description
`auto`	`true`	Déduit la valeur en fonction de la dernière série de caractères attribués au nom de l’objet blob. Si le nom de l’objet blob se termine `.gz`par , il suppose `gzip`. Sinon, il suppose `none`.
`gzip`		Force l’utilisation du décodeur gzip pour décompresser l’objet blob.
`none`		Force à traiter l’objet blob comme un objet blob qui ne nécessite pas de décompression.

L’extension ne prend pas en charge d’autres types de compression.

options

Type renvoyé

VOID

azure_storage.options_csv_get

Fonction qui agit en tant que fonction utilitaire, qui peut être appelée en tant que paramètre dans blob_get, et est utile pour décoder le contenu d’un fichier csv.

azure_storage.options_csv_get(delimiter text DEFAULT NULL::text, null_string text DEFAULT NULL::text, header boolean DEFAULT NULL::boolean, quote text DEFAULT NULL::text, escape text DEFAULT NULL::text, force_not_null text[] DEFAULT NULL::text[], force_null text[] DEFAULT NULL::text[], content_encoding text DEFAULT NULL::text);

autorisations

Tout utilisateur ou rôle peut appeler cette fonction.

Arguments

delimiter

text caractère qui sépare les colonnes dans chaque ligne (ligne) du fichier. Il doit s’agir d’un caractère de 1 octet unique. Bien que cette fonction prenne en charge les délimiteurs d’un nombre quelconque de caractères, si vous essayez d’utiliser plus d’un seul caractère de 1 octet, PostgreSQL signale une COPY delimiter must be a single one-byte character erreur.

null_string

text chaîne qui représente une valeur Null. La valeur par défaut est \N (barre oblique inverse-N) au format texte et une chaîne vide sans guillemets au format CSV. Vous préférerez peut-être une chaîne vide même au format texte pour les cas où vous ne souhaitez pas distinguer les valeurs nulles des chaînes vides.

boolean indicateur qui indique si le fichier contient une ligne d’en-tête avec les noms de chaque colonne du fichier. En sortie, la ligne initiale contient les noms de colonnes de la table.

quote

text caractère de guillemet à utiliser lorsqu’une valeur de données est entre guillemets. La valeur par défaut est double-quote (guillemet double). Il doit s’agir d’un caractère de 1 octet unique. Bien que cette fonction prenne en charge les délimiteurs d’un nombre quelconque de caractères, si vous essayez d’utiliser plus d’un seul caractère de 1 octet, PostgreSQL signale une COPY quote must be a single one-byte character erreur.

échappement

text caractère qui doit apparaître avant un caractère de données qui correspond à la valeur QUOTE. La valeur par défaut est identique à la valeur QUOTE (de sorte que le caractère de guillemet est doublé s’il apparaît dans les données). Il doit s’agir d’un caractère de 1 octet unique. Bien que cette fonction prenne en charge les délimiteurs d’un nombre quelconque de caractères, si vous essayez d’utiliser plus d’un seul caractère de 1 octet, PostgreSQL signale une COPY escape must be a single one-byte character erreur.

force_not_null

text[] ne correspondent pas aux valeurs des colonnes spécifiées par rapport à la chaîne Null. Dans le cas par défaut où la chaîne nulle est vide, cela signifie que les valeurs vides sont lues comme des chaînes de longueur nulle plutôt que des valeurs nulles, même si elles ne sont pas entre guillemets.

force_null

text[] correspond aux valeurs des colonnes spécifiées par rapport à la chaîne Null, même si elle est entre guillemets et si une correspondance est trouvée, définissez la valeur sur NULL. Dans le cas par défaut où la chaîne nulle est vide, elle convertit une chaîne vide entre guillemets en valeur NULL.

content_encoding

text nom de l’encodage avec lequel le fichier est encodé. Si l’option est omise, le codage client actuel est utilisé.

Type renvoyé

jsonb

azure_storage.options_copy

Fonction qui agit en tant que fonction utilitaire, qui peut être appelée en tant que paramètre dans blob_get. Il agit comme une fonction d’assistance pour options_csv_get, options_tsv et options_binary.

azure_storage.options_copy(delimiter text DEFAULT NULL::text, null_string text DEFAULT NULL::text, header boolean DEFAULT NULL::boolean, quote text DEFAULT NULL::text, escape text DEFAULT NULL::text, force_quote text[] DEFAULT NULL::text[], force_not_null text[] DEFAULT NULL::text[], force_null text[] DEFAULT NULL::text[], content_encoding text DEFAULT NULL::text);

autorisations

Tout utilisateur ou rôle peut appeler cette fonction.

Arguments

delimiter

null_string

en-tête

boolean indicateur qui indique si le fichier contient une ligne d’en-tête avec les noms de chaque colonne du fichier. En sortie, la ligne initiale contient les noms de colonnes de la table.

quote

échappement

force_quote

text[] force le guillemet à utiliser pour toutes les valeurs non NULL dans chaque colonne spécifiée. La sortie NULL n’est jamais entre guillemets. Si * est spécifié, les valeurs non nulles sont entre guillemets dans toutes les colonnes.

force_not_null

force_null

content_encoding

text nom de l’encodage avec lequel le fichier est encodé. Si l’option est omise, le codage client actuel est utilisé.

Type renvoyé

jsonb

azure_storage.options_tsv

Fonction qui agit en tant que fonction utilitaire, qui peut être appelée en tant que paramètre dans blob_get, et est utile pour décoder le contenu d’un fichier tsv.

azure_storage.options_tsv(delimiter text DEFAULT NULL::text, null_string text DEFAULT NULL::text, content_encoding text DEFAULT NULL::text);

autorisations

Tout utilisateur ou rôle peut appeler cette fonction.

Arguments

delimiter

null_string

content_encoding

text nom de l’encodage avec lequel le fichier est encodé. Si l’option est omise, le codage client actuel est utilisé.

Type renvoyé

jsonb

azure_storage.options_binary

Fonction qui agit en tant que fonction utilitaire, qui peut être appelée en tant que paramètre dans blob_get, et est utile pour décoder le contenu d’un fichier binaire.

azure_storage.options_binary(content_encoding text DEFAULT NULL::text);

autorisations

Tout utilisateur ou rôle peut appeler cette fonction.

Arguments

content_encoding

text nom de l’encodage avec lequel le fichier est encodé. Si l’option est omise, le codage client actuel est utilisé.

Type renvoyé

jsonb

Erreurs possibles

ERREUR : azure_storage : l’autorisation n’est pas suffisante pour effectuer l’opération demandée

Lors de l’exécution d’une des fonctions qui interagissent avec Stockage Azure (azure_storage.blob_listazure_storage.blob_getou azure_storage.blob_put) et que l’identité managée affectée par le système n’est pas accordée aux rôles ou autorisations de plan de données appropriés (généralement un minimum de contributeur aux données blob de stockage pour azure_storage.blob_put, et un minimum de lecteur de données blob de stockage pour les deux autres fonctions).

Il peut également s’agir du cas où vous avez déjà accordé les autorisations minimales requises, mais qu’elles ne sont pas encore en vigueur. Cela peut prendre quelques minutes jusqu’à ce que ces autorisations se propagent.

ERREUR : azure_storage : informations d’identification de stockage manquantes

Lors de l’exécution d’une des fonctions qui interagissent avec Stockage Azure (azure_storage.blob_listazure_storage.blob_getou azure_storage.blob_put) et les informations d’identification avec lesquelles vous souhaitez que l’extension s’authentifie auprès du compte de stockage ne soit pas inscrite à l’aide azure_storage.account_add.

ERREUR : azure_storage : erreur interne lors de la connexion

Lorsque l’identité managée affectée par le système n’est pas activée dans l’instance du serveur flexible.

ERREUR : azure_storage : format non valide des informations d’identification de stockage

Lorsque l’identité managée affectée par le système est activée sur l’instance du serveur flexible, mais que le serveur n’a pas été redémarré après l’avoir activé.

ERREUR : azure_storage : le user_or_role> utilisateur <actuel n’est pas autorisé à utiliser le compte <de stockage storage_account>

Lors de l’exécution d’une des fonctions qui interagissent avec Stockage Azure (azure_storage.blob_getazure_storage.blob_listou azure_storage.blob_put) avec un utilisateur ou un rôle qui n’est pas membre azure_storage_admin et qui n’est pas autorisé à azure_storage.account_user_addutiliser le compte de stockage référencé.

Exemples

Vous devez respecter les conditions préalables suivantes avant de pouvoir exécuter les exemples suivants :

Créez un compte de stockage Azure. Pour créer un compte Stockage Azure, si vous n’en avez pas déjà, personnalisez les valeurs de <resource_group>, <location>et <storage_account><blob_container>exécutez la commande Azure CLI suivante :

resource_group=<resource_group>
location=<location>
storage_account=<storage_account>
blob_container=<blob_container>
az group create --name $resource_group --location $location
az storage account create --resource-group $resource_group --name $storage_account --location $location --sku Standard_LRS --kind BlobStorage --public-network-access enabled --access-tier hot

Créez un conteneur d’objets blob. Pour créer le conteneur d’objets blob, exécutez l’interface Azure CLI suivante :
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Récupérez l’une des deux clés d’accès affectées au compte de stockage. Veillez à copier la valeur de votre access_key à mesure que vous devez la transmettre en tant qu’argument à azure_storage.account_add à une étape suivante. Pour récupérer la première des deux clés d’accès, exécutez la commande Azure CLI suivante :
```
access_key=$(az storage account keys list --resource-group $resource_group --account-name $storage_account --query [0].value)
echo "Following is the value of your access key:"
echo $access_key
```

Téléchargez le fichier avec le jeu de données utilisé pendant les exemples et chargez-le dans votre conteneur d’objets blob. Pour télécharger le fichier avec le jeu de données, exécutez la commande Azure CLI suivante :

mkdir --parents azure_storage_examples
cd azure_storage_examples
curl -O https://examples.citusdata.com/tutorial/events.csv
gzip -k events.csv
cp events.csv events_blob_without_extension
cp events.csv events_pipe.csv
cp events.csv.gz events_compressed
sed -i 's/,/|/g' events_pipe.csv
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "events*" --account-key $access_key --overwrite --output none --only-show-errors

Remarque

Vous pouvez répertorier les conteneurs ou les objets blob stockés dans ces conteneurs pour un compte de stockage spécifique, mais uniquement si votre utilisateur ou rôle PostgreSQL est autorisé sur la référence à ce compte de stockage à l’aide de azure_storage.account_user_add. Les membres du azure_storage_admin rôle bénéficient de ce privilège sur tous les comptes Stockage Azure qui ont été ajoutés à l’aide de azure_storage.account_add. Par défaut, seuls les membres du azure_pg_admin rôle sont accordés azure_storage_admin .

Créer une table dans laquelle les données sont chargées

Nous allons créer la table dans laquelle nous importons le contenu du fichier CSV que nous avons chargé dans le compte de stockage. Pour ce faire, connectez-vous à votre instance de Azure Database pour PostgreSQL serveur flexible à l’aide PgAdminde , psqlou au client de votre préférence, puis exécutez l’instruction suivante :

CREATE TABLE IF NOT EXISTS events
        (
         event_id bigint
        ,event_type text
        ,event_public boolean
        ,repo_id bigint
        ,payload jsonb
        ,repo jsonb
        ,user_id bigint
        ,org jsonb
        ,created_at timestamp without time zone
        );

Ajouter une clé d’accès au compte de stockage

Cet exemple montre comment ajouter une référence à un compte de stockage, ainsi que la clé d’accès de ce compte de stockage qui est nécessaire pour accéder à son contenu via les fonctionnalités fournies par l’extension azure_storage dans votre instance de serveur flexible Azure Database pour PostgreSQL.

<storage_account> doit être défini sur le nom de votre compte de stockage. Si vous avez utilisé les scripts précédents, cette valeur doit correspondre à la valeur que vous avez définie sur la variable d’environnement storage_account dans ces scripts.

De même, <access_key> vous devez définir la valeur que vous avez extraite de votre compte de stockage.

SELECT azure_storage.account_add('<storage_account>', '<access_key>');

Conseil

Si vous souhaitez récupérer le nom du compte de stockage et l’une de ses clés d’accès à partir de l’Portail Azure, recherchez votre compte de stockage, dans le menu de ressources, sélectionnez Clés d’accès, copiez le nom du compte de stockage et copiez la clé dans la section Clé1 (vous devez sélectionner Afficher en regard de la clé en premier).

Supprimer la référence au compte de stockage

Cet exemple montre comment supprimer toute référence à un compte de stockage, afin qu’aucun utilisateur de la base de données active ne puisse utiliser la azure_storage fonctionnalité d’extension pour accéder à ce compte de stockage.

SELECT azure_storage.account_remove('<storage_account>');

Accorder l’accès à un utilisateur ou à un rôle sur la référence de stockage Blob Azure

Cet exemple montre comment accorder l’accès à un utilisateur ou à un rôle nommé <regular_user>, afin que cet utilisateur PostgreSQL puisse utiliser l’extension azure_storage pour accéder aux objets blob stockés dans des conteneurs hébergés par le compte de stockage Azure référencé.

<regular_user> doit être défini sur le nom d’un utilisateur ou d’un rôle existant.

SELECT * FROM azure_storage.account_user_add('<storage_account>', '<regular_user>');

Répertorier toutes les références aux comptes de stockage Azure

Cet exemple montre comment identifier les comptes de stockage Azure auxquels l’extension azure_storage peut faire référence dans cette base de données, ainsi que le type d’authentification utilisé pour accéder à chaque compte de stockage et quels utilisateurs ou rôles sont autorisés, via la fonction azure_storage.account_user_add , à accéder à ce compte de stockage Azure via les fonctionnalités fournies par l’extension.

SELECT * FROM azure_storage.account_list();

Révoquer l’accès d’un utilisateur ou d’un rôle sur la référence de stockage Blob Azure

Cet exemple montre comment révoquer l’accès d’un utilisateur ou d’un rôle nommé <regular_user>, afin que cet utilisateur PostgreSQL ne puisse pas utiliser l’extension azure_storage pour accéder aux objets blob stockés dans des conteneurs hébergés par le compte de stockage Azure référencé.

<regular_user> doit être défini sur le nom d’un utilisateur ou d’un rôle existant.

SELECT * FROM azure_storage.account_user_remove('<storage_account>', '<regular_user>');

Lister tous les objets blob d’un conteneur

Cet exemple montre comment répertorier tous les objets blob existants dans le conteneur <container_name> du compte <storage_account>de stockage.

<blob_container> doit être défini sur le nom de votre conteneur d’objets blob. Si vous avez utilisé les scripts précédents, cette valeur doit correspondre à la valeur que vous avez définie sur la variable d’environnement blob_container dans ces scripts.

SELECT * FROM azure_storage.blob_list('<storage_account>','<blob_container>');

Répertorier les objets avec un préfixe de nom d’objet blob spécifique

Cet exemple montre comment répertorier tous les objets blob existants dans le conteneur <blob_container> du compte <storage_account>de stockage, dont le nom d’objet blob commence par <blob_name_prefix>.

<blob_name_prefix> doit être défini sur le préfixe que vous souhaitez que les objets blob énumérés soient inclus dans leurs noms. Si vous souhaitez renvoyer tous les objets blob, vous pouvez définir ce paramètre sur une chaîne vide ou ne pas même spécifier de valeur pour ce paramètre, auquel cas la valeur est par défaut une chaîne vide.

SELECT * FROM azure_storage.blob_list('<storage_account>','<blob_container>','<blob_name_prefix>');

Vous pouvez également utiliser la syntaxe suivante :

SELECT * FROM azure_storage.blob_list('<storage_account>','<blob_container>') WHERE path LIKE '<blob_name_prefix>%';

Lire du contenu à partir d’un objet blob dans un conteneur

La blob_get fonction récupère le contenu d’un objet blob spécifique (events.csv dans ce cas), dans le conteneur <blob_container> référencé du <storage_account> stockage. Pour blob_get savoir comment analyser les données, vous pouvez passer une valeur dans le formulaire NULL::table_name, où table_name fait référence à une table dont le schéma correspond à celui de l’objet blob en cours de lecture. Dans l’exemple, il fait référence à la events table que nous avons créée au début.

SELECT * FROM azure_storage.blob_get
        ('<storage_account>'
        ,'<blob_container>'
        ,'events.csv'
        , NULL::events)
LIMIT 5;

Vous pouvez également définir explicitement le schéma du résultat à l’aide de la AS clause après la fonction blob_get .

SELECT * FROM azure_storage.blob_get('<storage_account>','<blob_container>','events.csv.gz')
AS res (
         event_id BIGINT
        ,event_type TEXT
        ,event_public BOOLEAN
        ,repo_id BIGINT
        ,payload JSONB
        ,repo JSONB
        ,user_id BIGINT
        ,org JSONB
        ,created_at TIMESTAMP WITHOUT TIME ZONE)
LIMIT 5;

Utiliser l’option décodeur

Cet exemple illustre l’utilisation de l’option decoder . Normalement, le format est déduit de l’extension du fichier, mais lorsque le contenu du fichier n’a pas d’extension correspondante, vous pouvez transmettre l’argument decoder.

SELECT * FROM azure_storage.blob_get
        ('<storage_account>'
        ,'<blob_container>'
        ,'events_blob_without_extension'
        , NULL::events
        , decoder := 'csv')
LIMIT 5;

Utiliser la compression avec l’option decoder

Cet exemple montre comment appliquer l’utilisation de la compression gzip sur un objet blob compressé gzip dont le nom ne se termine pas par une extension .gz.

SELECT * FROM azure_storage.blob_get
        ('<storage_account>'
        ,'<blob_container>'
        ,'events_compressed'
        , NULL::events
        , decoder := 'csv'
        , compression := 'gzip')
LIMIT 5;

Importer du contenu filtré et modifier avant le chargement à partir de l’objet de format csv

Cet exemple illustre la possibilité de filtrer et de modifier le contenu importé à partir de l’objet blob, avant de le charger dans une table SQL.

SELECT concat('P-',event_id::text) FROM azure_storage.blob_get
        ('<storage_account>'
        ,'<blob_container>'
        ,'events.csv'
        , NULL::events)
WHERE event_type='PushEvent'
LIMIT 5;

Interroger le contenu à partir d’un fichier avec des en-têtes, des séparateurs personnalisés, des caractères d’échappement

Cet exemple montre comment utiliser des séparateurs personnalisés et des caractères d’échappement en passant le résultat de options_copy à l’argument options .

SELECT * FROM azure_storage.blob_get
        ('<storage_account>'
        ,'<blob_container>'
        ,'events_pipe.csv'
        ,NULL::events
        ,options := azure_storage.options_csv_get(delimiter := '|' , header := 'true')
        );

Requête d’agrégation sur le contenu d’un objet blob

Cet exemple montre comment effectuer des opérations d’agrégation sur des informations stockées dans un conteneur d’objets blob, sans avoir à importer le contenu de l’objet blob dans des tables PostgreSQL.

SELECT event_type, COUNT(*) FROM azure_storage.blob_get
        ('<storage_account>'
        ,'<blob_container>'
        ,'events.csv'
        , NULL::events)
GROUP BY event_type
ORDER BY 2 DESC
LIMIT 5;

Importer des données à l’aide d’une instruction COPY

L’exemple suivant montre l’importation de données à partir d’un objet blob appelé events.csv qui réside dans le conteneur <blob_container> d’objets blob dans le compte <storage_account>Stockage Azure, via la COPY commande :

Créez une table qui correspond au schéma du fichier source :

CREATE TABLE IF NOT EXISTS events
        (
         event_id bigint
        ,event_type text
        ,event_public boolean
        ,repo_id bigint
        ,payload jsonb
        ,repo jsonb
        ,user_id bigint
        ,org jsonb
        ,created_at timestamp without time zone
        );

Utilisez une instruction COPY pour copier des données dans la table cible. Spécifiez que la première ligne contient des en-têtes de colonne.
```
COPY events
FROM 'https://<storage_account>.blob.core.windows.net/<blob_container>/events.csv'
WITH (FORMAT 'csv', header);
```

Écrire du contenu dans un objet blob dans un conteneur

La blob_put fonction compose le contenu d’un objet blob spécifique (eventscopy.csv dans ce cas) et le charge dans le conteneur <blob_container> référencé du <storage_account> stockage. Cet exemple utilise blob_get pour construire un ensemble de cinq lignes, qui sont ensuite passées à la blob_put fonction d’agrégation qui les charge en tant qu’objet blob nommé eventscopy.csv.

SELECT azure_storage.blob_put
        ('<storage_account>'
        ,'<blob_container>'
        ,'eventscopy.csv'
        , top_5_events)
FROM (SELECT * FROM azure_storage.blob_get
                     ('<storage_account>'
                     ,'<blob_container>'
                     ,'events.csv'
                     , NULL::events) LIMIT 5) AS top_5_events;

Exporter des données à l’aide d’une instruction COPY

L’exemple suivant montre l’exportation de données d’une table appelée events, vers un objet blob appelé events_exported.csv qui réside dans le conteneur <blob_container> d’objets blob dans le compte <storage_account>Stockage Azure, via la COPY commande :

Créez une table qui correspond au schéma du fichier source :

CREATE TABLE IF NOT EXISTS events
        (
         event_id bigint
        ,event_type text
        ,event_public boolean
        ,repo_id bigint
        ,payload jsonb
        ,repo jsonb
        ,user_id bigint
        ,org jsonb
        ,created_at timestamp without time zone
        );

Chargez des données dans la table. Exécutez des instructions INSERT pour la remplir avec plusieurs lignes synthétiques ou utilisez les données d’importation à l’aide d’un exemple d’instruction COPY pour la remplir avec le contenu de l’exemple de jeu de données.
Utilisez une instruction COPY pour copier des données dans la table cible. Spécifiez que la première ligne contient des en-têtes de colonne.
```
COPY events
TO 'https://<storage_account>.blob.core.windows.net/<blob_container>/events_exported.csv'
WITH (FORMAT 'csv', header);
```

Partager vos suggestions et bogues avec l’équipe produit Azure Database pour PostgreSQL.

Partager via

Importer et exporter des données à l’aide de l’extension azure_storage dans Azure Database pour PostgreSQL - Serveur flexible

Vue d’ensemble de la procédure

Pour utiliser l’autorisation avec l’ID Microsoft Entra

Pour utiliser l’autorisation avec la clé partagée

Functions

azure_storage.account_add

autorisations

Arguments

account_name_p

account_key_p

account_config

Type renvoyé

azure_storage.account_options_managed_identity

autorisations

Arguments

name

type

Type renvoyé

azure_storage.account_options_credentials

autorisations

Arguments

name

credentials

type

Type renvoyé

azure_storage.account_options

autorisations

Arguments

name

auth_type

storage_type

credentials

Type renvoyé

azure_storage.account_remove

autorisations

Arguments

account_name_p

Type renvoyé

azure_storage.account_user_add

autorisations

Arguments

account_name_p

user_p

Type renvoyé

azure_storage.account_user_remove

autorisations

Arguments

account_name_p

user_p

Type renvoyé

azure_storage.account_list

autorisations

Arguments

Type renvoyé

azure_storage.blob_list

autorisations

Arguments

account_name

container_name

prefix

Type renvoyé

path

octets

last_modified

etag

content_type

content_encoding

content_hash

azure_storage.blob_get

autorisations

Arguments

account_name

container_name

path

rec

decoder

compression

options

Type renvoyé