cosmosdb_sql_request plugin

Article
10/15/2024

S’applique à : ✅Microsoft Fabric ✅Azure Data Explorer✅Azure Monitor ✅Microsoft Sentinel

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é 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é. Si `armResourceId` ce n’est pas spécifié, le jeton est utilisé directement pour accéder à la base de données Cosmos DB. Pour plus d’informations sur la méthode d’authentification par jeton, consultez Authentification et autorisation.
`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
Identité managée (recommandé)	Ajoutez `Authentication="Active Directory Managed Identity";User Id={object_id};` à la chaîne de connexion. La demande est effectuée au nom d’une identité managée qui doit disposer des autorisations appropriées pour la base de données. Pour activer l’authentification d’identité managée, vous devez ajouter l’identité managée à votre cluster et modifier la stratégie d’identité managée. Pour plus d’informations, consultez la stratégie d’identité managée.
ID de ressource Azure Resource Manager	Cette méthode d’authentification nécessite la `armResourceId` spécification et éventuellement la `token` valeur dans les 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é.
par jeton	Vous pouvez ajouter une valeur de jeton dans les options du plug-in. Le jeton doit appartenir à un principal disposant d’autorisations pertinentes. Pour améliorer la sécurité, masquez le jeton 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 de partenaire à partir d’une base de données Azure Cosmos DB avec des données partenaires 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’authentification par jeton

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)

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",
    dynamic({'armResourceId': '/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'})
) : (Id:long, Name:string, City:string)

Partage via