Sdílet prostřednictvím


Modul plug-incosmosdb_sql_request

Platí pro: ✅Microsoft FabricAzure Data Explorer✅Azure MonitorMicrosoft Sentinel

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 referenčními daty uloženými ve službě Azure Cosmos DB. Modul plug-in se vyvolá pomocí operátoru evaluate .

Syntaxe

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

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

Parametry

Název Type Požadováno Popis
Připojovací řetězec string ✔️ Připojovací řetězec, která odkazuje na kolekci Azure Cosmos DB k dotazování. Musí obsahovat AccountEndpoint, Database a Collection. Pokud se k ověřování používá hlavní klíč, může obsahovat 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'<AccountKey>'
SqlQuery string ✔️ Dotaz, který se má provést.
SqlParameters dynamic Objekt kontejneru vlastností, který se má předat jako parametry spolu s dotazem. Názvy parametrů musí začínat písmenem @.
OutputSchema Názvy a typy očekávaných sloupců výstupu cosmosdb_sql_request modulu plug-in. Použijte následující syntaxi: ( ColumnName : ColumnType [, ...] ). Zadání tohoto parametru umožňuje více optimalizací dotazů.
Možnosti dynamic Objekt kontejneru vlastností upřesňujícího nastavení. AccountKey Pokud není zadaný v connectionString, je pole tohoto parametru armResourceId povinné. Další informace najdete v tématu Podporované možnosti.

Podporované možnosti

Následující tabulka popisuje podporovaná pole parametru Možnosti .

Name Typ Popis
armResourceId string ID prostředku Azure Resource Manageru databáze Cosmos DB. Pokud klíč účtu není v argumentu připojovací řetězec zadaný, je toto pole povinné. V takovém případě armResourceId se používá k ověření ve službě Cosmos DB.
Příklad: armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'
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 armResourceId ověřováním pomocí Azure Resource Manageru. Pokud není zadaný, použije se token objektu zabezpečení, který dotaz provedl.

Pokud armResourceId není zadaný, token se použije přímo pro přístup k databázi Cosmos DB. Další informace o metodě ověřování tokenů najdete v tématu Ověřování a autorizace.
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í Popis
Spravovaná identita (doporučeno) Připojte Authentication="Active Directory Managed Identity";User Id={object_id}; se k připojovací řetězec. Žádost se provádí jménem spravované identity, která musí mít příslušná oprávnění k databázi.
Pokud chcete povolit ověřování spravovaných identit, musíte do clusteru přidat spravovanou identitu a změnit zásady spravované identity. Další informace najdete v tématu Zásady spravované identity.
ID prostředku Azure Resource Manageru Tato metoda ověřování vyžaduje zadání armResourceId a volitelně token v možnostech. Identifikuje armResourceId účet databáze Cosmos DB a token musí 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. Pokud není k dispozici, token použije se k ověřování 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ě zabezpečený, protože zahrnuje zahrnutí tajného klíče 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.
Token Do možností modulu plug-in můžete přidat hodnotu tokenu. Token musí patřit objektu zabezpečení s příslušnými oprávněními. Pokud chcete zvýšit zabezpečení, skryjte token jako obfuskovaný řetězcový literál.

Nastavení zásad bublinového popisku

Modul plug-in provádí bublinové popisky instance služby Azure Cosmos DB. Ujistěte se, že zásada popisku clusteru umožňuje 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 alter callout policy for cosmosdb CalloutType

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

Příklady

Následující příklady používají zástupný text v závorkách.

Dotazování služby Azure Cosmos DB pomocí schématu výstupu 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 skutečného dotazu ve službě Cosmos DB.

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) 

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'<AccountKey>',
  '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 pomocí parametrů

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

Dotazování služby Azure Cosmos DB a připojení dat pomocí databázové tabulky

Následující příklad spojí partnerová data ze služby Azure Cosmos DB s partnerskými daty v databázi pomocí Partner tohoto pole. Výsledkem je seznam partnerů s telefonními čísly, weby a kontaktní e-mailovou adresou seřazenou podle jména partnera.

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

Dotazování služby Azure Cosmos DB pomocí ověřování tokenů

Následující příklad spojí partnerová data ze služby Azure Cosmos DB s partnerskými daty v databázi pomocí Partner tohoto pole. Výsledkem je seznam partnerů s telefonními čísly, weby a kontaktní e-mailovou adresou seřazenou podle jména partnera.

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)

Dotazování služby Azure Cosmos DB pomocí ID prostředku Azure Resource Manageru pro ověřování

Následující příklad používá ID prostředku Azure Resource Manageru k ověřování a token Microsoft Entra žádajícího objektu zabezpečení, protože token není zadaný. Odešle dotaz SQL při výběru pouze konkrétních sloupců a určuje explicitní definice schématu.

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)