.ingestion dans
S’applique à : ✅Microsoft Fabric✅Azure Data Explorer
La commande .ingest into ingère des données dans une table en « extrayant » les données d’un ou 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 et les ingérer ensemble dans une seule table cible.
Les données sont ajoutées à la table sans affecter les enregistrements existants et sans modifier le schéma de la table.
Note
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é.
Note
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é. Pour plus d’informations sur les options d’ingestion, consultez vue d’ensemble de l’ingestion des données.
Autorisations
Vous devez disposer d’au moins 'ingestion de table autorisations pour exécuter cette commande.
Syntaxe
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
En savoir plus sur 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 valeur OperationId qui peut ensuite être utilisée avec la commande .show operation pour récupérer l’état d’achèvement de l’ingestion 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 seule chaîne de connexion doit faire référence à 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 l’ingestion à partir d’une requête d’une table externe . |
Note
Nous vous recommandons d’utiliser littéraux de chaîne obfusqués pour les SourceDataLocators. Le service nettoie les informations d’identification dans les traces internes et les messages d’erreur.
Propriétés d’ingestion
Important
Dans les données d’ingestion mises en file d’attente sont traitées par lot à l’aide des propriétés d’ingestion. Les propriétés de mappage d’ingestion plus distinctes utilisées, telles que différentes valeurs ConstValue, sont plus fragmentées l’ingestion devient, ce qui peut entraîner une dégradation des performances.
Le tableau suivant répertorie et décrit les propriétés prises en charge 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\"}}]")(déconseillé : 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 à l’aide d’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")(déconseillé : avroMappingReference, csvMappingReference, jsonMappingReference) |
creationTime |
Valeur datetime (mise en forme sous forme de chaîne ISO8601) à utiliser au moment de la 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. La substitution de la valeur par défaut est utile lors de l’ingestion de données plus anciennes, afin que la stratégie de rétention soit appliquée correctement. Quand elle est spécifiée, vérifiez que la propriété Lookback dans la stratégie de fusion Étendues effective de la table cible est alignée avec 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 (par défaut, false). Cette option s’applique uniquement aux commandes .append et .set-or-append. Les seules extensions de schéma autorisées ont plus de colonnes ajoutées à la table à la fin. |
Si le schéma de table d’origine est (a:string, b:int), une extension de schéma valide est (a:string, b:int, c:datetime, d:string), mais (a:string, c:datetime) n’est pas valide |
folder |
Pour commandes d' d’ingestion à partir d’une requête, le dossier à affecter à la table. Si la table existe déjà, cette propriété remplace le dossier de la table. | with (folder="Tables/Temporary") |
format |
Format de 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 réussir si la table a déjà des données marquées avec une balise de ingest-by: avec la même valeur. Cela garantit l’ingestion des données idempotentes. Pour plus d’informations, consultez ingestion par : balises. |
Les propriétés with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') indiquent que si des données avec la balise ingest-by:Part0001 existent déjà, ne terminez pas l’ingestion actuelle. S’il n’existe pas encore, cette nouvelle ingestion doit avoir ce jeu d’étiquettes (dans le cas où une prochaine ingestion tente d’ingérer à nouveau les mêmes données.) |
ignoreFirstRecord |
Valeur booléenne qui, si elle est définie sur true, indique que l’ingestion doit ignorer le premier enregistrement de chaque fichier. Cette propriété est utile pour les fichiers dans des formats CSVet similaires, si le premier enregistrement du fichier est le nom des colonnes. Par défaut, false est supposé. |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
Valeur booléenne qui, si elle est spécifiée, décrit s’il faut activer la stratégie de temps d’ingestion sur une table créée par cette commande. La valeur par défaut est true. |
with (policy_ingestiontime=false) |
recreate_schema |
Valeur booléenne qui, si elle est spécifiée, décrit si la commande peut recréer 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 des balises à associer aux données ingérées, mises en forme sous forme de chaîne JSON | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
Valeur booléenne qui, si elle est définie sur true, indique que les fichiers avec l’extension .gz ne sont pas compressés. Cet indicateur est parfois nécessaire lors de l’ingestion à partir d’Amazon AWS S3. |
with (treatGzAsUncompressed=true) |
validationPolicy |
Chaîne JSON qui indique les validations à exécuter pendant l’ingestion des données représentées au format CSV. Consultez d’ingestion des données pour obtenir une explication des différentes options. |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (il s’agit de la stratégie par défaut) |
zipPattern |
Utilisez cette propriété lors de l’ingestion de données à partir du stockage qui a une archive ZIP. Il s’agit d’une valeur de chaîne indiquant l’expression régulière à utiliser lors de la sélection des fichiers dans 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 l’accès 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 l’ingestion de données à partir d’un stockage externe.
| Méthode d’authentification | Azure Blob Storage / Data Lake Storage Gen2 | Data Lake Storage Gen1 |
|---|---|---|
| emprunt d’identité | Lecteur de données Blob de stockage | Lecteur |
| jeton d’accès partagé (SAP) | 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. | |
| d’identité managée | Lecteur de données Blob de stockage | Lecteur |
Retourne
Le résultat de la commande est une table avec autant d’enregistrements qu’il existe des 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 enregistrement unique est retourné avec un ID d’extension vide (zéro valeur).
| Nom | Type | Description |
|---|---|---|
| ExtentId | guid |
Identificateur unique de la partition de données générée par la commande. |
| ItemLoaded | string |
Un ou plusieurs fichiers de stockage liés à cet enregistrement. |
| Durée | timespan |
Durée nécessaire à l’ingestion. |
| HasErrors | bool |
Indique si cet enregistrement représente ou non un échec d’ingestion. |
| OperationId | guid |
ID unique représentant l’opération. Peut être utilisé avec la commande .show operation. |
Note
Cette commande ne modifie pas le schéma de la table en cours d’ingestion. Si nécessaire, les données sont « coerced » dans ce schéma pendant l’ingestion, et non pas de l’autre côté (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 base de données de lire deux objets blob à partir du Stockage Blob Azure en tant que fichiers CSV et d’ingérer leur contenu dans la table T. Le ... représente une signature d’accès partagé (SAP) stockage Azure qui donne un accès en lecture à chaque objet blob. Les chaînes obfuscatées (les h devant les valeurs de chaîne) sont utilisées pour s’assurer que la SAP n’est 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 identité managée
L’exemple suivant montre comment lire un fichier CSV à partir du Stockage Blob Azure et ingérer son contenu dans la table T à l’aide de l’authentification d’identité managée. L’authentification utilise l’ID d’identité managée (ID d’objet) affecté au stockage Blob Azure dans Azure. Pour plus d’informations, consultez Créer une identité managée pour les conteneurs de stockage.
.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 permet d’ingérer des données à partir d’Azure Data Lake Storage Gen2 (ADLSv2). Les informations d’identification utilisées ici (...) sont les informations d’identification du compte de stockage (clé partagée) et nous utilisons l’obfuscation de chaîne 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 fichier unique à partir d’Azure Data Lake Storage (ADLS). Il utilise les informations d’identification de l’utilisateur pour accéder à ADLS (il n’est donc pas nécessaire de traiter l’URI de stockage comme contenant un secret). Il montre également comment spécifier des 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 fichier unique à 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 fichier unique à 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')