cosmosdb_sql_request plugin

Gilt für: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Das cosmosdb_sql_request Plug-In sendet eine SQL-Abfrage an einen Azure Cosmos DB SQL-Netzwerkendpunkt und gibt die Ergebnisse der Abfrage zurück. Dieses Plug-In ist in erster Linie für die Abfrage kleiner Datasets konzipiert, z. B. das Anreichern von Daten mit Referenzdaten, die in Azure Cosmos DB gespeichert sind. Das Plug-In wird mit dem evaluate Operator aufgerufen.

Syntax

evaluatecosmosdb_sql_request ( ConnectionString , SqlQuery [ SqlParameters [, , Options]] ) [: OutputSchema]

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Unterstützte Optionen

In der folgenden Tabelle werden die unterstützten Felder des Optionsparameters beschrieben.

Authentifizierung und Autorisierung

Um einen Azure Cosmos DB SQL-Netzwerkendpunkt zu autorisieren, müssen Sie die Autorisierungsinformationen angeben. Die folgende Tabelle enthält die unterstützten Authentifizierungsmethoden und die Beschreibung für die Verwendung dieser Methode.

Festlegen der Beschriftungsrichtlinie

Das Plug-In führt Legenden an die Azure Cosmos DB-Instanz aus. Stellen Sie sicher, dass die Popuprichtlinie des Clusters Aufrufe vom Typ cosmosdb an den Ziel-CosmosDbUri aktiviert.

Das folgende Beispiel zeigt, wie die Popuprichtlinie für Azure Cosmos DB definiert wird. Es wird empfohlen, es auf bestimmte Endpunkte (my_endpoint1, my_endpoint2) zu beschränken.

[
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint1\\.documents\\.azure\\.com",
    "CanCall": true
  },
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint2\\.documents\\.azure\\.com",
    "CanCall": true
  }
]

Das folgende Beispiel zeigt einen Ändern des Popuprichtlinienbefehls für cosmosdb CalloutType.

.alter cluster policy callout @'[{"CalloutType": "cosmosdb", "CalloutUriRegex": "\\.documents\\.azure\\.com", "CanCall": true}]'

Beispiele

In den folgenden Beispielen wird Platzhaltertext in Klammern verwendet.

Abfragen von Azure Cosmos DB mit einem abfragedefinierten Ausgabeschema

Im folgenden Beispiel wird das Plug-In cosmosdb_sql_request verwendet, um eine SQL-Abfrage zu senden, während nur bestimmte Spalten ausgewählt werden. Diese Abfrage verwendet explizite Schemadefinitionen, die verschiedene Optimierungen zulassen, bevor die tatsächliche Abfrage für Cosmos DB ausgeführt wird.

evaluate cosmosdb_sql_request(
  'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>',
  'SELECT c.Id, c.Name from c') : (Id:long, Name:string) 

Abfragen einer Azure Cosmos DB

Im folgenden Beispiel wird das Plug-In cosmosdb_sql_request verwendet, um eine SQL-Abfrage zu senden, um Daten aus Azure Cosmos DB mithilfe seiner Azure Cosmos DB für NoSQL abzurufen.

evaluate cosmosdb_sql_request(
  'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>',
  'SELECT * from c') // OutputSchema is unknown, so it is not specified. This may harm the performance of the query.

Abfragen von Azure Cosmos DB mit Parametern

Im folgenden Beispiel werden SQL-Abfrageparameter verwendet und die Daten aus einem alternativen Bereich abgefragt. Weitere Informationen finden Sie unter preferredLocations.

evaluate cosmosdb_sql_request(
   'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>',
    "SELECT c.id, c.lastName, @param0 as Column0 FROM c WHERE c.dob >= '1970-01-01T00:00:00Z'",
    dynamic({'@param0': datetime(2019-04-16 16:47:26.7423305)}),
    dynamic({'preferredLocations': ['East US']})) : (Id:long, Name:string, Column0: datetime) 
| where lastName == 'Smith'

Abfragen von Azure Cosmos DB und Verknüpfen von Daten mit einer Datenbanktabelle

Im folgenden Beispiel werden Partnerdaten aus einer Azure Cosmos DB mit Partnerdaten in einer Datenbank mithilfe des Partner Felds verknüpft. Sie führt zu einer Liste von Partnern mit ihren Telefonnummern, der Website und der Kontakt-E-Mail-Adresse, die nach Partnername sortiert ist.

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>',
    "SELECT c.id, c.Partner, c. phoneNumber FROM c') : (Id:long, Partner:string, phoneNumber:string) 
| join kind=innerunique Partner on Partner
| project id, Partner, phoneNumber, website, Contact
| sort by Partner

Abfragen von Azure Cosmos DB mithilfe der Tokenauthentifizierung

Im folgenden Beispiel werden Partnerdaten aus einer Azure Cosmos DB mit Partnerdaten in einer Datenbank mithilfe des Partner Felds verknüpft. Sie führt zu einer Liste von Partnern mit ihren Telefonnummern, der Website und der Kontakt-E-Mail-Adresse, die nach Partnername sortiert ist.

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;',
    "SELECT c.Id, c.Name, c.City FROM c",
    dynamic(null),
    dynamic({'token': h'abc123...'})
) : (Id:long, Name:string, City:string)

Abfragen von Azure Cosmos DB mit Azure Resource Manager-Ressourcen-ID für die Authentifizierung

Im folgenden Beispiel wird die Azure Resource Manager-Ressourcen-ID für die Authentifizierung und das Microsoft Entra-Token des anfordernden Prinzipals verwendet, da kein Token angegeben ist. Sie sendet eine SQL-Abfrage, während sie nur bestimmte Spalten auswählt und explizite Schemadefinitionen angibt.

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;',
    "SELECT c.Id, c.Name, c.City FROM c",
    dynamic({'armResourceId': '/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'})
) : (Id:long, Name:string, City:string)