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.

Notes

L’opérateur externaldata prend en charge un ensemble spécifique de services de stockage, comme indiqué sous Chaînes de connexion de stockage.

Notes

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

Notes

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 grands volumes de données. Pour récupérer de gros 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.

Syntax

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

Découvrez les conventions de syntaxe.

Paramètres

Nom	Type	Obligatoire	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 facultatives prises en charge qui détermine 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 de 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 trueest , 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 dans le jeu de résultats de l’opérateur. Consultez Mappages de données.

Notes

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 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 de table externe.

Notes

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

Interroger les formats de données hiérarchiques

Pour interroger le format de données hiérarchique, tel que JSON, Parquet, Avroou ORC, ingestionMapping doit être spécifié dans les propriétés de l’opérateur. Dans cet exemple, un fichier JSON est 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 sur plusieurs lignes.

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