cosmosdb_sql_request plugin

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 eseguire query su set di dati di piccole dimensioni, ad esempio arricchire i 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	Tipo	Obbligatoria	Descrizione
ConnectionString	string	✔️	Stringa di connessione che punta all'insieme Azure Cosmos DB da eseguire una 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'R8PM...;'
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 cosmosdb_sql_request plug-in. Usare la sintassi seguente: (ColumnName:ColumnType [, ...] ). Specificando questo parametro è possibile abilitare più ottimizzazioni di query.
Opzioni	dynamic		Oggetto del contenitore delle proprietà delle impostazioni avanzate. Se un AccountKey oggetto non è specificato in ConnectionString, è necessario il armResourceId campo di questo parametro. Per altre informazioni, vedere Opzioni supportate.

Opzioni supportate

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

Nome	Tipo	Descrizione
armResourceId	string	L'ID risorsa di Azure Resource Manager del database Cosmos DB. Se una chiave dell'account non è specificata nell'argomento stringa di connessione, questo campo è obbligatorio. In tal caso, l'oggetto viene usato per eseguire l'autenticazione armResourceId a Cosmos DB. Esempio:/subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbacc
token	string	Token di accesso Microsoft Entra di un'entità con accesso al database Cosmos DB. Questo token viene usato insieme all'oggetto per eseguire l'autenticazione armResourceId con l'Resource Manager di Azure. Se non specificato, viene usato il token dell'entità che ha effettuato la query.
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. La tabella seguente fornisce i metodi di autenticazione supportati e la descrizione per l'uso di tale metodo.

Metodo di autenticazione	Descrizione
ID risorsa di Azure Resource Manager (consigliato)	Per l'autenticazione sicura, è consigliabile specificare e armResourceId facoltativamente nelle tokenopzioni. Identifica armResourceId l'account del database Cosmos DB e token deve essere un token di connessione valido Microsoft Entra per un'entità con autorizzazioni di accesso al database Cosmos DB. Se non token viene specificato alcun elemento, verrà usato il token Microsoft Entra dell'entità richiesta 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 e è meno resiliente alle modifiche future nella chiave dell'account. Per migliorare la sicurezza, nascondere il segreto come valore letterale stringa offuscato.

Impostare i criteri di callout

Il plug-in crea callout all'istanza di Azure Cosmos DB. Assicurarsi che il criterio di callout del cluster consenta le chiamate di tipo cosmosdball'uri CosmosDbUri di destinazione.

Nell'esempio seguente viene illustrato 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
  }
]

Nell'esempio seguente viene illustrato un comando alter callout policy per cosmosdbCalloutType

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

Esempio

Eseguire query su Azure Cosmos DB con uno schema di output definito da 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 che venga eseguita la query effettiva su 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) 

Eseguire query in Azure Cosmos DB

Nell'esempio seguente viene usato 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'R8PM...;',
  'SELECT * from c') // OutputSchema is unknown, so it is not specified. This may harm the performance of the query.

Eseguire query su Azure Cosmos DB con parametri

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

Questa funzionalità non è supportata in Monitoraggio di Azure