cosmosdb_sql_request plugin

O cosmosdb_sql_request plug-in envia uma consulta SQL para um ponto final de rede SQL do Azure Cosmos DB e devolve os resultados da consulta. Este plug-in foi concebido principalmente para consultar pequenos conjuntos de dados, por exemplo, para enriquecer dados com dados de referência armazenados no Azure Cosmos DB. O plug-in é invocado com o evaluate operador .

Syntax

evaluatecosmosdb_sql_request(ConnectionString,SqlQuery [,SqlParameters [,Opções]] ) [:OutputSchema]

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Tipo	Necessário	Descrição
ConnectionString	string	✔️	A cadeia de ligação que aponta para a coleção do Azure Cosmos DB para consulta. Tem de incluir AccountEndpoint, Base de Dados e Coleção. Pode incluir AccountKey se for utilizada uma chave mestra para autenticação. Para obter mais informações, veja Autenticação e autorização. Exemplo:'AccountEndpoint=https://cosmosdbacc.documents.azure.com/ ;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;'
SqlQuery	string	✔️	A consulta a executar.
SqlParameters	dynamic		O objeto property bag a transmitir como parâmetros juntamente com a consulta. Os nomes dos parâmetros têm de começar com @.
OutputSchema			Os nomes e tipos das colunas esperadas da saída do cosmosdb_sql_request plug-in. Utilize a seguinte sintaxe: (ColumnName:ColumnType [, ...] ). Especificar este parâmetro permite várias otimizações de consultas.
Opções	dynamic		Um objeto de conjunto de propriedades de definições avançadas. Se não for fornecido um AccountKey no ConnectionString, é necessário o armResourceId campo deste parâmetro. Para obter mais informações, veja Opções suportadas.

Opções suportadas

A tabela seguinte descreve os campos suportados do parâmetro Opções .

Nome	Tipo	Description
armResourceId	string	O Azure Resource Manager ID de recurso da base de dados do Cosmos DB. Se uma chave de conta não for fornecida no argumento cadeia de ligação, este campo é necessário. Nesse caso, o armResourceId é utilizado para autenticar no Cosmos DB. Exemplo:/subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbacc
token	string	Um Microsoft Entra token de acesso de um principal com acesso à base de dados do Cosmos DB. Este token é utilizado em conjunto com o armResourceId para autenticar com o Resource Manager do Azure. Se não for especificado, é utilizado o token do principal que efetuou a consulta.
preferredLocations	string	A região a partir da qual consultar os dados. Exemplo:['East US']

Autenticação e autorização

Para autorizar um ponto final de rede SQL do Azure Cosmos DB, tem de especificar as informações de autorização. A tabela seguinte fornece os métodos de autenticação suportados e a descrição de como utilizar esse método.

Método de autenticação	Description
ID de recurso do Azure Resource Manager (Recomendado)	Para autenticação segura, recomendamos que especifique e armResourceId , opcionalmente, nas tokenopções. O armResourceId identifica a conta de base de dados do Cosmos DB e token deve ser um token de portador Microsoft Entra válido para um principal com permissões de acesso à base de dados do Cosmos DB. Se não token for fornecido, será utilizado o token de Microsoft Entra do principal de pedido para autenticação.
Chave da conta	Pode adicionar a chave de conta diretamente ao argumento ConnectionString . No entanto, esta abordagem é menos segura, uma vez que envolve incluir o segredo no texto da consulta e é menos resiliente a futuras alterações na chave da conta. Para melhorar a segurança, oculte o segredo como um literal de cadeia oculta.

Definir política de nota de aviso

O plug-in faz notas de aviso para a instância do Azure Cosmos DB. Confirme que a política de nota de aviso do cluster permite chamadas do tipo cosmosdb para o CosmosDbUri de destino.

O exemplo seguinte mostra como definir a política de nota de aviso para o Azure Cosmos DB. Recomenda-se que o restrinja a pontos finais específicos (my_endpoint1, my_endpoint2).

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

O exemplo seguinte mostra um comando alterar a política de nota de aviso para cosmosdbCalloutType

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

Exemplos

Consultar o Azure Cosmos DB com um esquema de saída definido pela consulta

O exemplo seguinte utiliza o plug-in cosmosdb_sql_request para enviar uma consulta SQL ao selecionar apenas colunas específicas. Esta consulta utiliza definições de esquema explícitas que permitem várias otimizações antes de a consulta real ser executada no 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) 

Consultar o Azure Cosmos DB

O exemplo seguinte utiliza o plug-in cosmosdb_sql_request para enviar uma consulta SQL para obter dados do Azure Cosmos DB com o Azure Cosmos DB para 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.

Consultar o Azure Cosmos DB com parâmetros

O exemplo seguinte utiliza parâmetros de consulta SQL e consulta os dados de uma região alternativa. Para obter mais informações, consulte 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'

Esta capacidade não é suportada no Azure Monitor