cosmosdb_sql_request plug-in

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

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. Este plug-in foi projetado principalmente para consultar pequenos conjuntos de dados, por exemplo, enriquecer dados com dados de referência armazenados no Azure Cosmos DB. O plugin é invocado com o operador evaluate.

Sintaxe

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

Saiba mais sobre convenções de sintaxe.

Parâmetros

Opções suportadas

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

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 suportados e a descrição de como usar esse método.

Definir política de texto explicativo

O plug-in faz textos explicativos para a instância do Azure Cosmos DB. Certifique-se de que a política de texto explicativo do cluster habilite 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 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 a seguir mostra um comando alter callout policy para cosmosdbCalloutType

.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 autenticação de token

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>;',
    "SELECT c.Id, c.Name, c.City FROM c",
    dynamic(null),
    dynamic({'token': h'abc123...'})
) : (Id:long, Name:string, City:string)

Consultar o Azure Cosmos DB usando a ID de recurso do Azure Resource Manager para autenticação

O exemplo a seguir usa a ID de recurso do Azure Resource Manager 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",
    dynamic({'armResourceId': '/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'})
) : (Id:long, Name:string, City:string)