Modul plug-incosmosdb_sql_request
Platí pro: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft 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
evaluate
cosmosdb_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)