plug-in cosmosdb_sql_request

Artigo
10/15/2024

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. Esse 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 plug-in é invocado com o evaluate operador.

Sintaxe

evaluatecosmosdb_sql_request ( ConnectionString , SqlQuery [ , SqlParameters [ , Opções]] ) [: Esquema de saída]

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, Database e Collection. 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.
Parâmetros SQL	`dynamic`		O objeto do recipiente de propriedades a ser passado como parâmetros junto com a consulta. Os nomes dos parâmetros devem começar com `@`.
Esquema de saída			Os nomes e tipos das colunas esperadas da saída do `cosmosdb_sql_request` plug-in. 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 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`	A ID de recurso do Azure Resource Manager 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 Azure Resource Manager. Se não for especificado, o token da entidade de segurança que fez a consulta será usado. Se `armResourceId` não for especificado, o token será usado diretamente para acessar o banco de dados do Cosmos DB. Para obter mais informações sobre o método de autenticação de token, consulte Autenticação e autorização.
`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
Identidade gerenciada (recomendado)	Acrescentar `Authentication="Active Directory Managed Identity";User Id={object_id};` à cadeia de conexão. A solicitação é feita em nome de uma identidade gerenciada que deve ter as permissões apropriadas para o banco de dados. Para habilitar a autenticação de identidade gerenciada, você deve adicionar a identidade gerenciada ao cluster e alterar a política de identidade gerenciada. Para obter mais informações, consulte Política de identidade gerenciada.
ID de recurso do Azure Resource Manager	Este método de autenticação requer a especificação do `armResourceId` e, opcionalmente, o `token` nas opções. O `armResourceId` identifica a conta de banco de dados do Cosmos DB e 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 não `token` for fornecido, o token do 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 resiliente a alterações futuras na chave da conta. Para aumentar a segurança, oculte o segredo como um literal de cadeia de caracteres ofuscado.
Token	Você pode adicionar um valor de token nas opções do plug-in. O token deve pertencer a uma entidade com permissões relevantes. Para aumentar a segurança, oculte o token 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. É 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 de política de texto explicativo 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 for 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 parceiros de um Azure Cosmos DB com dados de parceiros 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 email 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 autenticação de token

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 do Microsoft Entra da entidade de segurança solicitante, já que um token não é especificado. Ele envia uma consulta SQL enquanto seleciona apenas colunas específicas e especifica definições de esquema explícitas.

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)

Compartilhar via