externaldata, opérateur

L’opérateur externaldata retourne une table dont le schéma est défini dans la requête elle-même et dont les données sont lues à partir d’un artefact de stockage externe, tel qu’un objet blob dans Stockage Blob Azure ou un fichier dans Azure Data Lake Storage.

Remarque

L’opérateur externaldata prend en charge un ensemble spécifique de services de stockage, comme indiqué sous Stockage chaîne de connexion s.

Remarque

L’opérateur externaldata prend en charge la clé SAP (Shared Access Signature), la clé d’accès et les méthodes d’authentification par jeton Microsoft Entra. Pour plus d’informations, consultez les méthodes d’authentification du stockage.

Remarque

Utilisez l’opérateur externaldata pour récupérer de petites tables de référence allant jusqu’à 100 Mo à partir d’un artefact de stockage externe. L’opérateur n’est pas conçu pour les volumes de données volumineux. Pour récupérer de grands volumes de données externes, nous vous recommandons d’ingérer les données externes dans Log Analytics en tant que journaux personnalisés. Cet opérateur n’est pas pris en charge lorsque le point de terminaison public de l’artefact de stockage se trouve derrière un pare-feu.

Syntaxe

externaldatacolumnName:columnType [, ...] )[ (storageConnectionString [, ...] ] [with ( propertyName = propertyValue [, ...])]

En savoir plus sur les conventions de syntaxe.

Paramètres

Nom	Type	Requise	Description
columnName, columnType	string	✔️	Liste des noms de colonnes et de leurs types. Cette liste définit le schéma de la table.
storageConnectionString	string	✔️	Un chaîne de connexion de stockage de l’artefact de stockage à interroger.
propertyName, propertyValue	string		Liste des propriétés prises en charge facultatives qui déterminent comment interpréter les données récupérées à partir du stockage.

Propriétés prises en charge

Propriété	Type	Description
format	string	Format des données. S’il n’est pas spécifié, une tentative est effectuée pour détecter le format de données à partir de l’extension de fichier. Par défaut, il s’agit de CSV. Tous les formats de données d’ingestion sont pris en charge.
ignoreFirstRecord	bool	Si la valeur est définie true, le premier enregistrement de chaque fichier est ignoré. Cette propriété est utile lors de l’interrogation de fichiers CSV avec des en-têtes.
ingestionMapping	string	Indique comment mapper des données du fichier source aux colonnes réelles du jeu de résultats de l’opérateur. Consultez Mappages de données.

Remarque

Cet opérateur n’accepte aucune entrée de pipeline.

Les limites de requête standard s’appliquent également aux requêtes de données externes.

Retours

L’opérateur externaldata retourne une table de données du schéma donné dont les données ont été analysées à partir de l’artefact de stockage spécifié, indiquée par le chaîne de connexion de stockage.

Exemples

Récupérer une liste d’ID d’utilisateur stockés dans Stockage Blob Azure

L’exemple suivant montre comment rechercher tous les enregistrements d’une table dont UserID la colonne se trouve dans un ensemble connu d’ID, conservés (un par ligne) dans un fichier de stockage externe. Étant donné que le format de données n’est pas spécifié, le format de données détecté est TXT.

Users
| where UserID in ((externaldata (UserID:string) [
    @"https://storageaccount.blob.core.windows.net/storagecontainer/users.txt" 
      h@"?...SAS..." // Secret token needed to access the blob
    ]))
| ...

Interroger plusieurs fichiers de données

L’exemple suivant interroge plusieurs fichiers de données stockés dans un stockage externe.

externaldata(Timestamp:datetime, ProductId:string, ProductDescription:string)
[
  h@"https://mycompanystorage.blob.core.windows.net/archivedproducts/2019/01/01/part-00000-7e967c99-cf2b-4dbb-8c53-ce388389470d.csv.gz?...SAS...",
  h@"https://mycompanystorage.blob.core.windows.net/archivedproducts/2019/01/02/part-00000-ba356fa4-f85f-430a-8b5a-afd64f128ca4.csv.gz?...SAS...",
  h@"https://mycompanystorage.blob.core.windows.net/archivedproducts/2019/01/03/part-00000-acb644dc-2fc6-467c-ab80-d1590b23fc31.csv.gz?...SAS..."
]
with(format="csv")
| summarize count() by ProductId

L’exemple ci-dessus peut être considéré comme un moyen rapide d’interroger plusieurs fichiers de données sans définir une table externe.

Remarque

Le partitionnement des données n’est pas reconnu par l’opérateur externaldata .

Interroger des formats de données hiérarchiques

Pour interroger le format de données hiérarchique, tel que JSON, , ParquetAvroou , ingestionMapping doit ORCêtre spécifié dans les propriétés de l’opérateur. Dans cet exemple, il existe un fichier JSON stocké dans Stockage Blob Azure avec le contenu suivant :

{
  "timestamp": "2019-01-01 10:00:00.238521",   
  "data": {    
    "tenant": "e1ef54a6-c6f2-4389-836e-d289b37bcfe0",   
    "method": "RefreshTableMetadata"   
  }   
}   
{
  "timestamp": "2019-01-01 10:00:01.845423",   
  "data": {   
    "tenant": "9b49d0d7-b3e6-4467-bb35-fa420a25d324",   
    "method": "GetFileList"   
  }   
}
...

Pour interroger ce fichier à l’aide de l’opérateur externaldata , un mappage de données doit être spécifié. Le mappage détermine comment mapper des champs JSON aux colonnes du jeu de résultats de l’opérateur :

externaldata(Timestamp: datetime, TenantId: guid, MethodName: string)
[ 
   h@'https://mycompanystorage.blob.core.windows.net/events/2020/09/01/part-0000046c049c1-86e2-4e74-8583-506bda10cca8.json?...SAS...'
]
with(format='multijson', ingestionMapping='[{"Column":"Timestamp","Properties":{"Path":"$.timestamp"}},{"Column":"TenantId","Properties":{"Path":"$.data.tenant"}},{"Column":"MethodName","Properties":{"Path":"$.data.method"}}]')

Le MultiJSON format est utilisé ici, car les enregistrements JSON uniques sont répartis en plusieurs lignes.

Pour plus d’informations sur la syntaxe de mappage, consultez Mappages de données.