Modul plug-incosmosdb_sql_request

Modul cosmosdb_sql_request plug-in odešle dotaz SQL do koncového bodu sítě SQL služby Azure Cosmos DB a vrátí výsledky dotazu. Tento modul plug-in je primárně určený pro dotazování malých datových sad, například rozšiřování dat o referenční data uložená ve službě Azure Cosmos DB. Modul plug-in se vyvolá pomocí operátoru evaluate .

Syntax

evaluatecosmosdb_sql_request(Connectionstring,SqlQuery [,SqlParameters [,Možnosti]] ) [:OutputSchema]

Přečtěte si další informace o konvencích syntaxe.

Parametry

Název	Typ	Vyžadováno	Popis
Connectionstring	string	✔️	Připojovací řetězec odkazující na kolekci Azure Cosmos DB, která se má dotazovat. Musí obsahovat AccountEndpoint, Database a Collection. Pokud se k ověřování používá hlavní klíč, může obsahovat klíč AccountKey . Další informace najdete v tématu Ověřování a autorizace. Příklad:'AccountEndpoint=https://cosmosdbacc.documents.azure.com/ ;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;'
SqlQuery	string	✔️	Dotaz, který se má provést.
Parametry SQL	dynamic		Objekt kontejneru vlastností, který se má předat jako parametry spolu s dotazem. Názvy parametrů musí začínat na @.
OutputSchema			Názvy a typy očekávaných sloupců výstupu modulu plug-in cosmosdb_sql_request Použijte následující syntaxi: (ColumnName:ColumnType [, ...] ). Zadáním tohoto parametru povolíte více optimalizací dotazů.
Možnosti	dynamic		Objekt kontejneru vlastností upřesňujících nastavení. AccountKey Pokud není v connectionString zadaný parametr , je armResourceId pole tohoto parametru povinné. Další informace najdete v tématu Podporované možnosti.

Podporované možnosti

Následující tabulka popisuje podporovaná pole parametru Options .

Název	Typ	Description
armResourceId	string	Azure Resource Manager ID prostředku databáze Cosmos DB. Pokud v argumentu připojovací řetězec není zadaný klíč účtu, je toto pole povinné. V takovém případě se použije k ověření ve službě armResourceId Cosmos DB . Příklad:/subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbacc
token	string	Přístupový token Microsoft Entra objektu zabezpečení s přístupem k databázi Cosmos DB. Tento token se používá společně s tokenem armResourceId k ověření ve službě Azure Resource Manager. Pokud není zadaný, použije se token objektu zabezpečení, který dotaz provedl.
preferredLocations	string	Oblast, ze které se mají data dotazovat. Příklad:['East US']

Ověřování a autorizace

Pokud chcete autorizovat koncový bod sítě SQL služby Azure Cosmos DB, musíte zadat informace o autorizaci. Následující tabulka obsahuje podporované metody ověřování a popis použití této metody.

Metoda ověřování	Description
ID prostředku Azure Resource Manager (doporučeno)	V případě zabezpečeného ověřování doporučujeme v možnostecharmResourceId zadat volitelně token a . Identifikuje armResourceId účet databáze Cosmos DB a token měl by být platným nosným tokenem Microsoft Entra pro objekt zabezpečení s přístupovými oprávněními k databázi Cosmos DB. token Pokud není zadaný, použije se k ověření token Microsoft Entra objektu zabezpečení žádosti.
Klíč účtu	Klíč účtu můžete přidat přímo do argumentu ConnectionString . Tento přístup je ale méně bezpečný, protože zahrnuje zahrnutí tajného kódu do textu dotazu a je méně odolný vůči budoucím změnám klíče účtu. Pokud chcete zvýšit zabezpečení, skryjte tajný kód jako obfuskovaný řetězcový literál.

Nastavení zásad popisku

Modul plug-in provádí bublinové popisky pro instanci služby Azure Cosmos DB. Ujistěte se, že zásady popisku clusteru povolují volání typu cosmosdb do cílového identifikátoru CosmosDbUri.

Následující příklad ukazuje, jak definovat zásady popisku pro službu Azure Cosmos DB. Doporučujeme ho omezit na konkrétní koncové body (my_endpoint1, my_endpoint2).

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

Následující příklad ukazuje příkaz zásady alter callout pro cosmosdbCalloutType.

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

Příklady

Dotazování služby Azure Cosmos DB s využitím výstupního schématu definovaného dotazem

Následující příklad používá modul plug-in cosmosdb_sql_request k odeslání dotazu SQL při výběru pouze konkrétních sloupců. Tento dotaz používá explicitní definice schématu, které umožňují různé optimalizace před spuštěním vlastního dotazu ve službě Cosmos DB.

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) 

Dotazování na Azure Cosmos DB

Následující příklad používá modul plug-in cosmosdb_sql_request k odeslání dotazu SQL pro načtení dat ze služby Azure Cosmos DB pomocí služby Azure Cosmos DB for NoSQL.

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.

Dotazování služby Azure Cosmos DB s parametry

Následující příklad používá parametry dotazu SQL a dotazuje se na data z alternativní oblasti. Další informace naleznete v tématu 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'

Tato funkce není ve službě Azure Monitor podporována.