cosmosdb_sql_request plugin

Articolo
10/15/2024

Si applica a: ✅Microsoft Fabric ✅Azure Esplora dati ✅ Azure Monitor✅Microsoft Sentinel

Il cosmosdb_sql_request plug-in invia una query SQL a un endpoint di rete SQL di Azure Cosmos DB e restituisce i risultati della query. Questo plug-in è progettato principalmente per l'esecuzione di query su set di dati di piccole dimensioni, ad esempio l'arricchimento dei dati con dati di riferimento archiviati in Azure Cosmos DB. Il plug-in viene richiamato con l'operatore evaluate .

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome	Digita	Obbligatorio	Descrizione
ConnectionString	`string`	✔️	Il stringa di connessione che punta alla raccolta di Azure Cosmos DB per eseguire query. Deve includere AccountEndpoint, Database e Raccolta. Può includere AccountKey se viene usata una chiave master per l'autenticazione. Per altre informazioni, vedere Autenticazione e autorizzazione. Esempio: `'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>'`
SqlQuery	`string`	✔️	Query da eseguire.
SqlParameters	`dynamic`		Oggetto contenitore delle proprietà da passare come parametri insieme alla query. I nomi dei parametri devono iniziare con `@`.
OutputSchema			Nomi e tipi delle colonne previste dell'output del plug-in `cosmosdb_sql_request` . Usare la sintassi seguente: `(` ColumnName `:`* ColumnType* [`,` ...] `)`. Se si specifica questo parametro, vengono abilitate più ottimizzazioni delle query.
Opzioni	`dynamic`		Oggetto contenitore delle proprietà di impostazioni avanzate. Se non `AccountKey` viene specificato in ConnectionString, il `armResourceId` campo di questo parametro è obbligatorio. Per altre informazioni, vedere Opzioni supportate.

Opzioni supportate

Nella tabella seguente vengono descritti i campi supportati del parametro Options .

Nome	Tipo	Descrizione
`armResourceId`	`string`	ID risorsa di Azure Resource Manager del database Cosmos DB. Se non viene specificata una chiave dell'account nell'argomento stringa di connessione, questo campo è obbligatorio. In questo caso, viene usato per eseguire l'autenticazione `armResourceId` in Cosmos DB. Esempio: `armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'`
`token`	`string`	Token di accesso Microsoft Entra di un'entità di sicurezza con accesso al database Cosmos DB. Questo token viene usato insieme a per eseguire l'autenticazione `armResourceId` con Azure Resource Manager. Se non specificato, viene usato il token dell'entità che ha eseguito la query. Se `armResourceId` non viene specificato, il token viene usato direttamente per accedere al database Cosmos DB. Per altre informazioni sul metodo di autenticazione del token, vedere Autenticazione e autorizzazione.
`preferredLocations`	`string`	Area da cui eseguire query sui dati. Esempio: `['East US']`

Autenticazione e autorizzazione

Per autorizzare un endpoint di rete SQL di Azure Cosmos DB, è necessario specificare le informazioni di autorizzazione. Nella tabella seguente vengono forniti i metodi di autenticazione supportati e la descrizione per l'utilizzo di tale metodo.

Authentication method	Descrizione
Identità gestita (scelta consigliata)	Aggiungere `Authentication="Active Directory Managed Identity";User Id={object_id};` al stringa di connessione. La richiesta viene effettuata per conto di un'identità gestita che deve disporre delle autorizzazioni appropriate per il database. Per abilitare l'autenticazione dell'identità gestita, è necessario aggiungere l'identità gestita al cluster e modificare i criteri di identità gestita. Per altre informazioni, vedere Criteri di identità gestita.
ID della risorsa Azure Resource Manager	Questo metodo di autenticazione richiede di specificare `armResourceId` e facoltativamente nelle `token` opzioni. `armResourceId` Identifica l'account del database Cosmos DB e `token` deve essere un token di connessione Microsoft Entra valido per un'entità di sicurezza con autorizzazioni di accesso al database Cosmos DB. Se non viene specificato alcun valore `token` , verrà usato il token Microsoft Entra dell'entità richiedente per l'autenticazione.
Chiave dell'account	È possibile aggiungere la chiave dell'account direttamente all'argomento ConnectionString . Tuttavia, questo approccio è meno sicuro perché implica l'inclusione del segreto nel testo della query ed è meno resiliente alle modifiche future nella chiave dell'account. Per migliorare la sicurezza, nascondere il segreto come valore letterale stringa offuscato.
Token	È possibile aggiungere un valore del token nelle opzioni del plug-in. Il token deve appartenere a un'entità con autorizzazioni pertinenti. Per migliorare la sicurezza, nascondere il token come valore letterale stringa offuscato.

Impostare i criteri di callout

Il plug-in effettua callout all'istanza di Azure Cosmos DB. Assicurarsi che i criteri di callout del cluster consentano le chiamate di tipo cosmosdb all'uri CosmosDbUri di destinazione.

L'esempio seguente illustra come definire i criteri di callout per Azure Cosmos DB. È consigliabile limitarlo a endpoint specifici (my_endpoint1, my_endpoint2).

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

L'esempio seguente mostra un comando alter callout policy per cosmosdb CalloutType

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

Esempi

Negli esempi seguenti viene usato il testo segnaposto, tra parentesi quadre.

Eseguire query in Azure Cosmos DB con uno schema di output definito dalla query

Nell'esempio seguente viene usato il plug-in cosmosdb_sql_request per inviare una query SQL selezionando solo colonne specifiche. Questa query usa definizioni di schema esplicite che consentono varie ottimizzazioni prima dell'esecuzione della query effettiva su 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)

Eseguire query in Azure Cosmos DB

L'esempio seguente usa il plug-in cosmosdb_sql_request per inviare una query SQL per recuperare i dati da Azure Cosmos DB usando Azure Cosmos DB per 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.

Eseguire query in Azure Cosmos DB con parametri

L'esempio seguente usa parametri di query SQL ed esegue query sui dati da un'area alternativa. Per ulteriori informazioni, vedere 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'

Eseguire query su Azure Cosmos DB e unire i dati con una tabella di database

L'esempio seguente unisce i dati dei partner da un'istanza di Azure Cosmos DB con i dati dei partner in un database usando il Partner campo . Viene visualizzato un elenco di partner con i numeri di telefono, il sito Web e l'indirizzo di posta elettronica di contatto ordinati in base al nome del partner.

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

Eseguire query in Azure Cosmos DB usando l'autenticazione basata su token

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)

Eseguire query in Azure Cosmos DB usando l'ID risorsa di Azure Resource Manager per l'autenticazione

L'esempio seguente usa l'ID risorsa di Azure Resource Manager per l'autenticazione e il token Microsoft Entra dell'entità richiedente, poiché non viene specificato un token. Invia una query SQL selezionando solo colonne specifiche e specifica definizioni di schema esplicite.

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)

Condividi tramite