operator externaldata

De externaldata operator retourneert een tabel waarvan het schema is gedefinieerd in de query zelf en waarvan de gegevens worden gelezen uit een extern opslagartefact, zoals een blob in Azure Blob Storage of een bestand in Azure Data Lake Storage.

Notitie

De externaldata operator ondersteunt een specifieke set opslagservices, zoals vermeld onder Opslagverbindingsreeksen.

Notitie

De externaldata operator ondersteunt SAS-sleutel (Shared Access Signature), toegangssleutel en Microsoft Entra tokenverificatiemethoden. Zie Opslagverificatiemethoden voor meer informatie.

Notitie

Gebruik de externaldata operator om kleine referentietabellen van maximaal 100 MB op te halen uit een extern opslagartefact. De operator is niet ontworpen voor grote gegevensvolumes. Als u grote hoeveelheden externe gegevens wilt ophalen, raden we u aan de externe gegevens als aangepaste logboeken op te nemen in Log Analytics. Deze operator wordt niet ondersteund wanneer het openbare eindpunt van het opslagartefact zich achter een firewall bevindt.

Syntax

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

Meer informatie over syntaxisconventies.

Parameters

Naam	Type	Vereist	Beschrijving
columnName, columnType	string	✔️	Een lijst met kolomnamen en hun typen. Deze lijst definieert het schema van de tabel.
storageConnectionString	string	✔️	Een opslag verbindingsreeks van het opslagartefact om query's op uit te voeren.
propertyName, propertyValue	string		Een lijst met optionele ondersteunde eigenschappen die bepaalt hoe de gegevens die uit de opslag worden opgehaald, moeten worden geïnterpreteerd.

Ondersteunde eigenschappen

Eigenschap	Type	Description
indeling	string	De gegevensindeling. Als u dit niet opgeeft, wordt er een poging gedaan om het gegevensformaat van de bestandsextensie te detecteren. De standaardwaarde is CSV. Alle indelingen voor opnamegegevens worden ondersteund.
ignoreFirstRecord	bool	Als dit is ingesteld op true, wordt de eerste record in elk bestand genegeerd. Deze eigenschap is handig bij het uitvoeren van query's op CSV-bestanden met headers.
ingestionMapping	string	Hiermee wordt aangegeven hoe gegevens uit het bronbestand worden toegewezen aan de werkelijke kolommen in de resultatenset van de operator. Zie gegevenstoewijzingen.

Notitie

Deze operator accepteert geen pijplijninvoer.

Standaardquerylimieten zijn ook van toepassing op externe gegevensquery's.

Retouren

De externaldata operator retourneert een gegevenstabel van het opgegeven schema waarvan de gegevens zijn geparseerd uit het opgegeven opslagartefact, aangegeven door de opslag verbindingsreeks.

Voorbeelden

Een lijst met gebruikers-id's ophalen die zijn opgeslagen in Azure Blob Storage

In het volgende voorbeeld ziet u hoe u alle records kunt vinden in een tabel waarvan de UserID kolom in een bekende set id's valt, die (één per regel) worden opgeslagen in een extern opslagbestand. Omdat de gegevensindeling niet is opgegeven, is TXTde gedetecteerde gegevensindeling .

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

Query's uitvoeren op meerdere gegevensbestanden

In het volgende voorbeeld wordt een query uitgevoerd op meerdere gegevensbestanden die zijn opgeslagen in externe opslag.

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

Het bovenstaande voorbeeld kan worden gezien als een snelle manier om query's uit te voeren op meerdere gegevensbestanden zonder een externe tabel te definiëren.

Notitie

Gegevenspartitionering wordt niet herkend door de externaldata operator.

Query's uitvoeren op hiërarchische gegevensindelingen

Als u een query wilt uitvoeren op hiërarchische gegevensindeling, zoals JSON, AvroParquet, of ORC, ingestionMapping moet worden opgegeven in de operatoreigenschappen. In dit voorbeeld is er een JSON-bestand opgeslagen in Azure Blob Storage met de volgende inhoud:

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

Als u een query wilt uitvoeren op dit bestand met behulp van de externaldata operator, moet een gegevenstoewijzing worden opgegeven. De toewijzing bepaalt hoe JSON-velden moeten worden toegewezen aan de kolommen van de operatorresultatenset:

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

De MultiJSON indeling wordt hier gebruikt omdat afzonderlijke JSON-records worden overspannen in meerdere regels.

Zie gegevenstoewijzingen voor meer informatie over de toewijzingssyntaxis.