externaldata-Operator

Der externaldata Operator gibt eine Tabelle zurück, deren Schema in der Abfrage selbst definiert ist und deren Daten aus einem externen Speicherartefakt wie einem Blob in Azure Blob Storage oder einer Datei in Azure Data Lake Storage gelesen werden.

Hinweis

Der externaldata Operator unterstützt einen bestimmten Satz von Speicherdiensten, wie unter Speicherverbindungszeichenfolgen aufgeführt.

Hinweis

Der externaldata Operator unterstützt SAS-Schlüssel (Shared Access Signature), Zugriffsschlüssel und Microsoft Entra Tokenauthentifizierungsmethoden. Weitere Informationen finden Sie unter Speicherauthentifizierungsmethoden.

Hinweis

Verwenden Sie den externaldata Operator, um kleine Verweistabellen von bis zu 100 MB aus einem externen Speicherartefakt abzurufen. Der Operator ist nicht für große Datenvolumes konzipiert. Zum Abrufen großer Mengen externer Daten wird empfohlen, die externen Daten als benutzerdefinierte Protokolle in Log Analytics zu erfassen. Dieser Operator wird nicht unterstützt, wenn sich der öffentliche Endpunkt des Speicherartefakts hinter einer Firewall befindet.

Syntax

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

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name	Typ	Erforderlich	BESCHREIBUNG
columnName, columnType	string	✔️	Eine Liste von Spaltennamen und deren Typen. Diese Liste definiert das Schema der Tabelle.
storageConnectionString	string	✔️	Ein Speicher Verbindungszeichenfolge des abzufragenden Speicherartefakts.
propertyName, propertyValue	string		Eine Liste optionaler unterstützter Eigenschaften , die bestimmt, wie die aus dem Speicher abgerufenen Daten interpretiert werden.

Unterstützte Eigenschaften

Eigenschaft	Typ	BESCHREIBUNG
format	string	Das Datenformat. Wenn nicht angegeben, wird versucht, das Datenformat aus der Dateierweiterung zu erkennen. Der Standardwert lautet CSV. Alle Erfassungsdatenformate werden unterstützt.
ignoreFirstRecord	bool	Bei Festlegung auf truewird der erste Datensatz in jeder Datei ignoriert. Diese Eigenschaft ist hilfreich beim Abfragen von CSV-Dateien mit Headern.
ingestionMapping	string	Gibt an, wie Daten aus der Quelldatei den tatsächlichen Spalten im Operatorresultset zugeordnet werden. Weitere Informationen finden Sie unter Data mappings (Datenzuordnungen).

Hinweis

Dieser Operator akzeptiert keine Pipelineeingaben.

Standardabfragegrenzwerte gelten auch für externe Datenabfragen.

Gibt zurück

Der externaldata Operator gibt eine Datentabelle des angegebenen Schemas zurück, deren Daten aus dem angegebenen Speicherartefakt analysiert wurden, angegeben durch den Speicher Verbindungszeichenfolge.

Beispiele

Abrufen einer Liste der in Azure Blob Storage gespeicherten Benutzer-IDs

Das folgende Beispiel zeigt, wie Sie alle Datensätze in einer Tabelle finden, deren UserID Spalte in einen bekannten Satz von IDs fällt, die in einer externen Speicherdatei gespeichert sind (eine pro Zeile). Da das Datenformat nicht angegeben ist, ist TXTdas erkannte Datenformat .

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
    ]))
| ...

Abfragen mehrerer Datendateien

Im folgenden Beispiel werden mehrere Datendateien abfragt, die im externen Speicher gespeichert sind.

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

Das obige Beispiel kann als schnelle Möglichkeit zum Abfragen mehrerer Datendateien ohne Definition einer externen Tabelle betrachtet werden.

Hinweis

Die Datenpartitionierung wird vom externaldata Operator nicht erkannt.

Abfragen hierarchischer Datenformate

Zum Abfragen von hierarchischen Datenformaten wie JSON, ParquetAvro, oder ingestionMappingORCmuss in den Operatoreigenschaften angegeben werden. In diesem Beispiel wird eine JSON-Datei in Azure Blob Storage mit folgendem Inhalt gespeichert:

{
  "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"   
  }   
}
...

Um diese Datei mit dem externaldata Operator abzufragen, muss eine Datenzuordnung angegeben werden. Die Zuordnung schreibt vor, wie JSON-Felder den Resultsetspalten des Operators zugeordnet werden:

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"}}]')

Das MultiJSON Format wird hier verwendet, da einzelne JSON-Einträge in mehrere Zeilen überspannt werden.

Weitere Informationen zur Zuordnungssyntax finden Sie unter Datenzuordnungen.