Share via

Ingestion à partir du stockage

  • Article

La commande .ingest into ingère les données dans une table en « tirant » (pull) les données d’un ou de plusieurs fichiers de stockage cloud. Par exemple, la commande peut récupérer 1 000 objets blob au format CSV à partir du Stockage blob Azure, les analyser puis les ingérer dans une table cible. Les données sont ajoutées à la table sans affecter les enregistrements existants, et sans modifier le schéma de la table.

Notes

Cette méthode d’ingestion est destinée à l’exploration et au prototypage. Ne l’utilisez pas dans des scénarios de production ou de volume élevé.

Autorisations

Vous devez disposer au moins des autorisations d’ingestion de table pour exécuter cette commande.

Syntax

.ingest[async] intotableTableName SourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]

Découvrez les conventions de syntaxe.

Paramètres

Nom Type Obligatoire Description
async string Si elle est spécifiée, la commande retourne immédiatement et continue l’ingestion en arrière-plan. Les résultats de la commande incluent une OperationId valeur qui peut ensuite être utilisée avec la .show operation commande pour récupérer l’achèvement de l’ingestion status et les résultats.
TableName string ✔️ Nom de la table dans laquelle ingérer des données. Le nom de la table est toujours relatif à la base de données dans le contexte. Si aucun objet de mappage de schéma n’est fourni, le schéma de la base de données dans le contexte est utilisé.
SourceDataLocator string ✔️ Liste unique ou séparée par des virgules de chaînes de connexion de stockage. Une chaîne de connexion ne doit référencer qu’un seul fichier hébergé par un compte de stockage. L’ingestion de plusieurs fichiers peut être effectuée en spécifiant plusieurs chaînes de connexion ou en ingérant à partir d’une requête d’une table externe.

Notes

Nous vous recommandons d’utiliser des littéraux de chaîne obfusqués pour sourceDataPointer. Le service nettoie les informations d’identification dans les traces internes et les messages d’erreur.

Propriétés d’ingestion

Important

Le tableau suivant liste les propriétés prises en charge par Azure Data Explorer, les décrit et fournit des exemples :

Propriété Description Exemple
ingestionMapping Valeur de chaîne qui indique comment mapper les données du fichier source aux colonnes réelles de la table. Définissez la valeur format avec le type de mappage approprié. Consultez Mappages de données. with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")
(sont dépréciés : avroMapping, csvMapping, jsonMapping)
ingestionMappingReference Valeur de chaîne qui indique comment mapper les données du fichier source aux colonnes réelles de la table en utilisant un objet de stratégie de mappage nommé. Définissez la valeur format avec le type de mappage approprié. Consultez Mappages de données. with (format="csv", ingestionMappingReference = "Mapping1")
(sont dépréciés : avroMappingReference, csvMappingReference, jsonMappingReference)
creationTime Valeur DateHeure (sous forme de chaîne ISO8601) à utiliser comme heure de création des étendues de données ingérées. Si elle n’est pas spécifiée, la valeur actuelle (now()) est utilisée. En cas d’ingestion de données anciennes, vous pouvez remplacer les valeurs par défaut pour que la stratégie de conservation soit appliquée correctement. Lorsqu’elle est spécifiée, assurez-vous que la propriété Lookback de la stratégie de fusion des étendues effective de la table cible est alignée sur la valeur spécifiée. with (creationTime="2017-02-13")
extend_schema Valeur booléenne qui, si elle est spécifiée, indique à la commande d’étendre le schéma de la table (la valeur par défaut est false). Cette option s’applique uniquement aux commandes .append et .set-or-append. Les seules extensions de schéma autorisées sont celles pour lesquelles des colonnes supplémentaires sont ajoutées à la fin de la table. Si le schéma de la table d’origine est (a:string, b:int), une extension de schéma valide est (a:string, b:int, c:datetime, d:string) et non (a:string, c:datetime)
folder Pour les commandes ingest-from-query, dossier à attribuer à la table. Si la table existe déjà, cette propriété remplace le dossier de la table. with (folder="Tables/Temporary")
format Format des données (voir formats de données pris en charge). with (format="csv")
ingestIfNotExists Valeur de chaîne qui, si elle est spécifiée, empêche l’ingestion de s’effectuer correctement si la table a déjà des données balisées avec une balise ingest-by: de la même valeur. Cela garantit une ingestion des données idempotent. Pour plus d’informations, consultez Étiquettes ingest-by:. Les propriétés with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') indiquent que si des données existent déjà avec l’étiquette ingest-by:Part0001, vous ne devez pas effectuer l’ingestion actuelle. Si elles n’existent pas déjà, l’étiquette doit être définie dans la nouvelle ingestion (au cas où une future ingestion tente d’ingérer une nouvelle fois les mêmes données).
ignoreFirstRecord Valeur booléenne qui, si elle a la valeur true, indique que l’ingestion doit ignorer le premier enregistrement de chaque fichier. Cette propriété est utile pour les fichiers au format CSV (et similaires) si le premier enregistrement dans le fichier représente les noms de colonne. Par défaut, la valeur false est supposée. with (ignoreFirstRecord=false)
policy_ingestiontime Valeur booléenne qui, si elle est spécifiée, indique d’activer ou non la stratégie de durée d’ingestion sur une table créée par cette commande. Par défaut, il s’agit de true. with (policy_ingestiontime=false)
recreate_schema Valeur booléenne qui, si elle est spécifiée, indique si la commande peut recréer ou non le schéma de la table. Cette propriété s’applique uniquement à la commande .set-or-replace. Cette propriété est prioritaire sur la propriété extend_schema si les deux sont définies. with (recreate_schema=true)
tags Liste d’étiquettes à associer aux données ingérées, sous forme de chaîne JSON with (tags="['Tag1', 'Tag2']")
validationPolicy Chaîne JSON qui indique les validations à exécuter pendant l’ingestion des données représentées au format CSV. Consultez Ingestion des données pour avoir une explication des différentes options. with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (stratégie par défaut)
zipPattern Utilisez cette propriété en cas d’ingestion des données à partir d’un stockage qui a une archive ZIP. Il s’agit d’une valeur de chaîne indiquant l’expression régulière à utiliser pour sélectionner les fichiers de l’archive ZIP à ingérer. Tous les autres fichiers de l’archive sont ignorés. with (zipPattern="*.csv")

Authentification et autorisation

Chaque chaîne de connexion de stockage indique la méthode d’autorisation à utiliser pour accéder au stockage. Selon la méthode d’autorisation, le principal peut avoir besoin d’autorisations sur le stockage externe pour effectuer l’ingestion.

Le tableau suivant répertorie les méthodes d’authentification prises en charge et les autorisations nécessaires pour ingérer des données à partir d’un stockage externe.

Méthode d'authentification Stockage Blob Azure / Data Lake Storage Gen2 Data Lake Storage Gen 1
Emprunt d'identité Lecteur des données blob du stockage Lecteur
Jeton d’accès partagé (SAS) Liste + Lecture Cette méthode d’authentification n’est pas prise en charge dans Gen1.
jeton d’accès Microsoft Entra
Clé d’accès au compte de stockage Cette méthode d’authentification n’est pas prise en charge dans Gen1.
Identité gérée Lecteur des données blob du stockage Lecteur

Retours

Le résultat de la commande est une table avec autant d’enregistrements qu’il y a de partitions de données (« étendues ») générées par la commande. Si aucune partition de données n’a été générée, un seul enregistrement est retourné avec un ID d’étendue vide (zéro).

Name Type Description
ExtentId guid Identificateur unique pour la partition de données qui a été générée par la commande.
ItemLoaded string Un ou plusieurs fichiers de stockage associés à cet enregistrement.
Duration timespan Durée du processus d’ingestion.
HasErrors bool Indique si cet enregistrement constitue ou non un échec d’ingestion.
OperationId guid ID unique représentant l’opération. Peut être utilisé avec la commande .show operation.

Notes

Cette commande ne modifie pas le schéma de la table en cours d’ingestion. Si nécessaire, les données sont « forcées » dans ce schéma lors de l’ingestion. Toutefois, cela n’est pas possible dans l’autre sens (les colonnes supplémentaires sont ignorées, et les colonnes manquantes sont traitées comme des valeurs Null).

Exemples

Stockage Blob Azure avec signature d’accès partagé

L’exemple suivant indique à votre cluster de lire deux objets blob de Stockage Blob Azure en tant que fichiers CSV et d’ingérer leur contenu dans la table T. ... représente une signature d’accès partagé (SAS) du Stockage Azure qui donne un accès en lecture à chaque objet blob. Notez également l’utilisation de chaînes obfusquées (le h devant les valeurs de chaîne) qui permet de garantir que la signature d’accès partagé ne sera jamais enregistrée.

.ingest into table T (
    h'https://contoso.blob.core.windows.net/container/file1.csv?...',
    h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)

Stockage Blob Azure avec une identité managée

L’exemple suivant montre comment lire un fichier CSV à partir de Stockage Blob Azure et ingérer son contenu dans une table T à l’aide de l’authentification d’identité managée. Pour plus d’informations sur la méthode d’authentification d’identité managée, consultez Vue d’ensemble de l’authentification d’identité managée.

.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')

Azure Data Lake Storage Gen 2

L’exemple suivant concerne l’ingestion de données à partir de Azure Data Lake Storage Gen 2 (ADLSv2). Les informations d’identification utilisées ici (...) sont celles du compte de stockage (clé partagée), et nous utilisons l’obfuscation des chaînes uniquement pour la partie secrète de la chaîne de connexion.

.ingest into table T (
  'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)

Azure Data Lake Storage

L’exemple suivant ingère un seul fichier à partir de Azure Data Lake Storage (ADLS). Il utilise les informations d’identification de l’utilisateur pour accéder à ADLS (de sorte qu’il n’est pas nécessaire de traiter l’URI de stockage comme s’il contenait un secret). Il montre également comment spécifier les propriétés d’ingestion.

.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
  with (format='csv')

Amazon S3 avec une clé d’accès

L’exemple suivant ingère un seul fichier à partir d’Amazon S3 à l’aide d’un ID de clé d’accès et d’une clé d’accès secrète.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
  with (format='csv')

Amazon S3 avec une URL présignée

L’exemple suivant ingère un seul fichier à partir d’Amazon S3 à l’aide d’une URL présignée.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
  with (format='csv')