Plug-in cosmosdb_sql_request

O cosmosdb_sql_request plug-in envia uma consulta SQL para um ponto de extremidade de rede SQL do Azure Cosmos DB e retorna os resultados da consulta. Esse plug-in foi projetado principalmente para consultar pequenos conjuntos de dados, por exemplo, enriquecendo dados com dados de referência armazenados no Azure Cosmos DB. O plugin é invocado com o evaluate operador.

Sintaxe

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

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Digitar	Obrigatória	Descrição
ConnectionString	string	✔️	A cadeia de conexão que aponta para a coleção do Azure Cosmos DB a ser consultada. Ele deve incluir AccountEndpoint, Banco de Dados e Coleção. Ele pode incluir AccountKey se uma chave mestra for usada para autenticação. Para obter mais informações, consulte Autenticação e autorização. Exemplo: 'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>'
SqlQuery	string	✔️	A consulta a ser executada.
SqlParameters	dynamic		O objeto do conjunto de propriedades a ser passado como parâmetros junto com a consulta. Os nomes dos parâmetros devem começar com @.
OutputSchema			Os nomes e tipos das colunas esperadas da saída do cosmosdb_sql_request plugin. Use a seguinte sintaxe: ( ColumnName : ColumnType [, ...] ). A especificação desse parâmetro permite várias otimizações de consulta.
Opções	dynamic		Um objeto de pacote de propriedades de configurações avançadas. Se um AccountKey não for fornecido no ConnectionString, o armResourceId campo desse parâmetro será obrigatório. Para obter mais informações, consulte Opções com suporte.

Opções com suporte

A tabela a seguir descreve os campos com suporte do parâmetro Options .

Nome	Tipo	Descrição
armResourceId	string	A ID de recurso do Gerenciador de Recursos do Azure do banco de dados do Cosmos DB. Se uma chave de conta não for fornecida no argumento da cadeia de conexão, esse campo será obrigatório. Nesse caso, o armResourceId é usado para autenticar no Cosmos DB. Exemplo: armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'
token	string	Um token de acesso do Microsoft Entra de uma entidade de segurança com acesso ao banco de dados do Cosmos DB. Esse token é usado junto com o armResourceId para autenticar com o Gerenciador de Recursos do Azure. Se não for especificado, o token da entidade de segurança que fez a consulta será usado.
preferredLocations	string	A região a partir da qual consultar os dados. Exemplo: ['East US']

Autenticação e autorização

Para autorizar um ponto de extremidade de rede SQL do Azure Cosmos DB, você precisa especificar as informações de autorização. A tabela a seguir fornece os métodos de autenticação com suporte e a descrição de como usar esse método.

Método de autenticação	Descrição
ID de recurso do Azure Resource Manager (recomendado)	Para autenticação segura, recomendamos especificar o armResourceId e opcionalmente o token nas opções. O armResourceId identifica a conta de banco de dados do Cosmos DB e o deve ser um token de portador válido do token Microsoft Entra para uma entidade de segurança com permissões de acesso ao banco de dados do Cosmos DB. Se nenhum for token fornecido, o token Microsoft Entra da entidade de segurança solicitante será usado para autenticação.
Chave de conta	Você pode adicionar a chave de conta diretamente ao argumento ConnectionString . No entanto, essa abordagem é menos segura, pois envolve a inclusão do segredo no texto da consulta e é menos resistente a alterações futuras na chave da conta. Para aumentar a segurança, oculte o segredo como um literal de cadeia de caracteres ofuscado.

Definir política de texto explicativo

O plug-in faz textos explicativos para a instância do Azure Cosmos DB. Verifique se a política de texto explicativo do cluster habilita chamadas do tipo cosmosdb para o CosmosDbUri de destino.

O exemplo a seguir mostra como definir a política de texto explicativo para o Azure Cosmos DB. Recomenda-se restringi-lo a pontos de extremidade 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 a seguir mostra um comando alter callout policy para cosmosdb CalloutType

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

Exemplos

Os exemplos a seguir usam texto de espaço reservado, entre colchetes.

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

O exemplo a seguir usa o plug-in cosmosdb_sql_request para enviar uma consulta SQL enquanto seleciona apenas colunas específicas. Essa consulta usa definições de esquema explícitas que permitem várias otimizações antes que a consulta real seja executada no 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) 

Consultar o Azure Cosmos DB

O exemplo a seguir usa o plug-in cosmosdb_sql_request para enviar uma consulta SQL para buscar dados do Azure Cosmos DB usando seu Azure Cosmos DB para 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.

Consultar o Azure Cosmos DB com parâmetros

O exemplo a seguir usa 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'<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'

Consultar o Azure Cosmos DB e unir dados com uma tabela de banco de dados

O exemplo a seguir une dados de parceiro de um Azure Cosmos DB com dados de parceiro em um banco de dados usando o Partner campo. Isso resulta em uma lista de parceiros com seus números de telefone, site e endereço de e-mail de contato classificados por nome de parceiro.

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

Consultar o Azure Cosmos DB usando a ID de recurso do Gerenciador de Recursos do Azure para autenticação

O exemplo a seguir usa a ID de recurso do Gerenciador de Recursos do Azure para autenticação e o token Microsoft Entra da entidade solicitante, já que um token não é especificado. Ele envia uma consulta SQL enquanto seleciona apenas colunas específicas e especifica definições explícitas de esquema.

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)

Essa funcionalidade não é compatível com o Azure Monitor