cosmosdb_sql_request plugin

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

Syntax

evaluatecosmosdb_sql_request(Connectionstring,SqlQuery [,SqlParameters [,Optionen]] ) [:OutputSchema]

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name	Typ	Erforderlich	BESCHREIBUNG
ConnectionString	string	✔️	Die Verbindungszeichenfolge, die auf die abzufragende Azure Cosmos DB-Sammlung verweist. Sie muss AccountEndpoint, Database und Collection enthalten. Es kann AccountKey enthalten, wenn ein master Schlüssel für die Authentifizierung verwendet wird. Weitere Informationen finden Sie unter Authentifizierung und Autorisierung. Beispiel:'AccountEndpoint=https://cosmosdbacc.documents.azure.com/ ;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;'
SqlQuery	string	✔️	Die auszuführende Abfrage.
SqlParameters	dynamic		Das Eigenschaftsbehälterobjekt, das zusammen mit der Abfrage als Parameter übergeben werden soll. Parameternamen müssen mit @beginnen.
OutputSchema			Die Namen und Typen der erwarteten Spalten der cosmosdb_sql_request Plug-In-Ausgabe. Verwenden Sie die folgende Syntax: (ColumnName:ColumnType [, ...] ). Die Angabe dieses Parameters ermöglicht mehrere Abfrageoptimierungen.
Optionen	dynamic		Ein Eigenschaftenbehälterobjekt mit erweiterten Einstellungen. Wenn in AccountKeyConnectionString nicht angegeben wird, ist das armResourceId Feld dieses Parameters erforderlich. Weitere Informationen finden Sie unter Unterstützte Optionen.

Unterstützte Optionen

In der folgenden Tabelle werden die unterstützten Felder des Options-Parameters beschrieben.

Name	Typ	BESCHREIBUNG
armResourceId	string	Die Azure Resource Manager-Ressourcen-ID der Cosmos DB-Datenbank. Wenn im Argument Verbindungszeichenfolge kein Kontoschlüssel angegeben wird, ist dieses Feld erforderlich. In diesem Fall wird verwendet armResourceId , um sich bei Cosmos DB zu authentifizieren. Beispiel:/subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbacc
token	string	Ein Microsoft Entra Zugriffstoken eines Prinzipals mit Zugriff auf die Cosmos DB-Datenbank. Dieses Token wird zusammen mit dem armResourceId verwendet, um sich beim Azure-Resource Manager zu authentifizieren. Falls nicht angegeben, wird das Token des Prinzipals verwendet, der die Abfrage erstellt hat.
preferredLocations	string	Der Bereich, aus dem die Daten abfragt werden sollen. Beispiel:['East US']

Authentifizierung und Autorisierung

Zum Autorisieren für einen SQL-Netzwerkendpunkt von Azure Cosmos DB müssen Sie die Autorisierungsinformationen angeben. Die folgende Tabelle enthält die unterstützten Authentifizierungsmethoden und die Beschreibung der Verwendung dieser Methode.

Authentifizierungsmethode	BESCHREIBUNG
Azure Resource Manager-Ressourcen-ID (empfohlen)	Für die sichere Authentifizierung wird empfohlen, die armResourceId und optional token in den Optionen anzugeben. Identifiziert armResourceId das Cosmos DB-Datenbankkonto, und das token sollte ein gültiges Microsoft Entra Bearertoken für einen Prinzipal mit Zugriffsberechtigungen für die Cosmos DB-Datenbank sein. Wenn kein token angegeben wird, wird das Microsoft Entra Token des anfordernden Prinzipals für die Authentifizierung verwendet.
Kontoschlüssel	Sie können den Kontoschlüssel direkt zum Argument ConnectionString hinzufügen. Dieser Ansatz ist jedoch weniger sicher, da er das Geheimnis in den Abfragetext einschließt und weniger resilient gegenüber zukünftigen Änderungen im Kontoschlüssel ist. Um die Sicherheit zu erhöhen, blenden Sie das Geheimnis als verschleiertes Zeichenfolgenliteral aus.

Festlegen einer Beschriftungsrichtlinie

Das Plug-In stellt Dem Azure Cosmos DB-instance. Stellen Sie sicher, dass die Beschriftungsrichtlinie des Clusters Aufrufe vom Typ cosmosdb an den CosmosDbUri-Zieltyp aktiviert.

Im folgenden Beispiel wird gezeigt, wie Die Legendenrichtlinie für Azure Cosmos DB definiert wird. Es wird empfohlen, sie 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 Befehl zur Änderung der Legendenrichtlinie für cosmosdbCalloutType.

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

Beispiele

Abfragen von Azure Cosmos DB mit einem abfragedefiniertem 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 eigentliche Abfrage für Cosmos DB ausgeführt wird.

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

Abfragen einer Azure Cosmos DB

Im folgenden Beispiel wird das cosmosdb_sql_request-Plug-In verwendet, um eine SQL-Abfrage zum Abrufen von Daten aus Azure Cosmos DB mithilfe von Azure Cosmos DB for NoSQL zu senden.

evaluate cosmosdb_sql_request(
  'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;',
  '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 einer alternativen Region abgefragt. Weitere Informationen finden Sie unter preferredLocations.

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;',
    "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'

Diese Funktion wird in Azure Monitor nicht unterstützt.