cosmosdb_sql_request, plug-in

Le cosmosdb_sql_request plug-in envoie une requête SQL à un point de terminaison réseau SQL Azure Cosmos DB et retourne les résultats de la requête. Ce plug-in est principalement conçu pour interroger de petits jeux de données, par exemple, enrichir des données avec des données de référence stockées dans Azure Cosmos DB. Le plug-in est appelé avec l’opérateur evaluate .

Syntaxe

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

En savoir plus sur les conventions de syntaxe.

Paramètres

Nom	Type	Requise	Description
ConnectionString	string	✔️	Le chaîne de connexion qui pointe vers la collection Azure Cosmos DB à interroger. Il doit inclure AccountEndpoint, Database et Collection. Il peut inclure AccountKey si une clé principale est utilisée pour l’authentification. Pour plus d’informations, consultez Authentification et autorisation. Exemple: 'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>'
SqlQuery	string	✔️	Requête à exécuter.
SqlParameters	dynamic		Objet conteneur de propriétés à transmettre en tant que paramètres avec la requête. Les noms de paramètres doivent commencer par @.
OutputSchema			Noms et types des colonnes attendues de la sortie du cosmosdb_sql_request plug-in. Utilisez la syntaxe suivante : ( ColumnName : ColumnType [, ...] ). La spécification de ce paramètre active plusieurs optimisations de requête.
Options	dynamic		Objet conteneur de propriétés de paramètres avancés. Si une AccountKey valeur n’est pas fournie dans ConnectionString, le armResourceId champ de ce paramètre est requis. Pour plus d’informations, consultez les options prises en charge.

Options prises en charge

Le tableau suivant décrit les champs pris en charge du paramètre Options .

Nom	Type	Description
armResourceId	string	ID de ressource Azure Resource Manager de la base de données Cosmos DB. Si une clé de compte n’est pas fournie dans l’argument chaîne de connexion, ce champ est requis. Dans ce cas, il est utilisé pour s’authentifier armResourceId auprès de Cosmos DB. Exemple: armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'
token	string	Jeton d’accès Microsoft Entra d’un principal ayant accès à la base de données Cosmos DB. Ce jeton est utilisé conjointement avec l’authentification armResourceId auprès d’Azure Resource Manager. S’il n’est pas spécifié, le jeton du principal qui a effectué la requête est utilisé.
preferredLocations	string	Région à partir de laquelle interroger les données. Exemple : ['East US']

Authentification et autorisation

Pour autoriser un point de terminaison réseau SQL Azure Cosmos DB, vous devez spécifier les informations d’autorisation. Le tableau suivant fournit les méthodes d’authentification prises en charge et la description de l’utilisation de cette méthode.

Méthode d'authentification	Description
ID de ressource Azure Resource Manager (recommandé)	Pour l’authentification sécurisée, nous vous recommandons de spécifier et armResourceId éventuellement les token options. Identifie armResourceId le compte de base de données Cosmos DB et doit token être un jeton de porteur Microsoft Entra valide pour un principal disposant d’autorisations d’accès à la base de données Cosmos DB. Si aucun n’est token fourni, le jeton Microsoft Entra du principal demandeur est utilisé pour l’authentification.
Clé de compte	Vous pouvez ajouter la clé de compte directement à l’argument ConnectionString . Toutefois, cette approche est moins sécurisée, car elle implique l’inclusion du secret dans le texte de la requête et est moins résiliente aux modifications futures de la clé de compte. Pour améliorer la sécurité, masquez le secret en tant que littéral de chaîne obfusqué.

Définir la stratégie de légende

Le plug-in effectue des légendes à l’instance Azure Cosmos DB. Assurez-vous que la stratégie de légende du cluster active les appels de type cosmosdb vers cosmosDbUri cible.

L’exemple suivant montre comment définir la stratégie de légende pour Azure Cosmos DB. Il est recommandé de le restreindre à des points de terminaison spécifiques (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’exemple suivant montre une commande de stratégie de modification de légende pour cosmosdb CalloutType

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

Exemples

Les exemples suivants utilisent du texte d’espace réservé, entre crochets.

Interroger Azure Cosmos DB avec un schéma de sortie défini par la requête

L’exemple suivant utilise le plug-in cosmosdb_sql_request pour envoyer une requête SQL tout en sélectionnant uniquement des colonnes spécifiques. Cette requête utilise des définitions de schéma explicites qui permettent différentes optimisations avant l’exécution de la requête réelle sur 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) 

Interroger Azure Cosmos DB

L’exemple suivant utilise le plug-in cosmosdb_sql_request pour envoyer une requête SQL pour extraire des données à partir d’Azure Cosmos DB à l’aide de son azure Cosmos DB pour 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.

Interroger Azure Cosmos DB avec des paramètres

L’exemple suivant utilise des paramètres de requête SQL et interroge les données d’une autre région. Pour plus d’informations, consultez 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'

Interroger Azure Cosmos DB et joindre des données avec une table de base de données

L’exemple suivant joint les données du partenaire à partir d’une base de données Azure Cosmos DB avec des données de partenaire dans une base de données à l’aide du Partner champ. Elle génère une liste de partenaires avec leurs numéros de téléphone, leur site web et leur adresse e-mail de contact triées par nom de partenaire.

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

Interroger Azure Cosmos DB à l’aide de l’ID de ressource Azure Resource Manager pour l’authentification

L’exemple suivant utilise l’ID de ressource Azure Resource Manager pour l’authentification et le jeton Microsoft Entra du principal demandeur, car un jeton n’est pas spécifié. Il envoie une requête SQL tout en sélectionnant uniquement des colonnes spécifiques et spécifie des définitions de schéma explicites.

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;',
    "SELECT c.Id, c.Name, c.City FROM c",
    armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'
) : (Id:long, Name:string, City:string)

Cette fonctionnalité n’est pas prise en charge dans Azure Monitor.