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 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	Obrigatório	Descrição
ConnectionString	string	✔️	O cadeia de conexão que aponta para a coleção do Azure Cosmos DB a ser consultada. Ele deve incluir AccountEndpoint, Database e Collection. Ele poderá incluir AccountKey se uma chave de master 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'R8PM...;'
SqlQuery	string	✔️	A consulta a ser executada.
SqlParameters	dynamic		O objeto do recipiente de propriedades a ser passado como parâmetros junto com a consulta. Os nomes de parâmetro devem começar com @.
OutputSchema			Os nomes e tipos das colunas esperadas da saída do cosmosdb_sql_request plug-in. Use a seguinte sintaxe: (ColumnName:ColumnType [, ...] ). Especificar esse parâmetro habilita várias otimizações de consulta.
Opções	dynamic		Um objeto de recipiente de propriedades de configurações avançadas. Se um AccountKey não for fornecido no ConnectionString, o armResourceId campo desse parâmetro será necessá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	O Azure Resource Manager ID do recurso do banco de dados do Cosmos DB. Se uma chave de conta não for fornecida no argumento cadeia de conexão, esse campo será necessário. Nesse caso, o armResourceId é usado para autenticar no Cosmos DB. Exemplo:/subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbacc
token	string	Um token de acesso 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 Resource Manager 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 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 do recurso de Resource Manager do Azure (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 token deve ser um token de portador de Microsoft Entra válido para uma entidade de segurança com permissões de acesso para o banco de dados do Cosmos DB. Se não token for 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 incluir o segredo no texto da consulta e é menos resiliente a alterações futuras na chave da conta. Para aprimorar 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 permite 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. É recomendável 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 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 por consulta

O exemplo a seguir usa o plug-in cosmosdb_sql_request para enviar uma consulta SQL ao selecionar 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'R8PM...;',
  '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 for 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 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'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'

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