Compartir a través de

cosmosdb_sql_request plugin

  • Artículo

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

El cosmosdb_sql_request complemento envía una consulta SQL a un punto de conexión de red de SQL de Azure Cosmos DB y devuelve los resultados de la consulta. Este complemento está diseñado principalmente para consultar conjuntos de datos pequeños, por ejemplo, enriquecer datos con datos de referencia almacenados en Azure Cosmos DB. El complemento se invoca con el evaluate operador .

Sintaxis

evaluatecosmosdb_sql_request ( ConnectionString SqlQuery [, SqlParameters [, Options]] ) [: OutputSchema] ,

Obtenga más información sobre las convenciones de sintaxis.

Parámetros

Nombre Type Obligatorio Descripción
ConnectionString string ✔️ El cadena de conexión que apunta a la colección de Azure Cosmos DB que se va a consultar. Debe incluir AccountEndpoint, Database y Collection. Puede incluir AccountKey si se usa una clave maestra para la autenticación. Para obtener más información, consulte Autenticación y autorización.
Ejemplo: 'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>'
SqlQuery string ✔️ Consulta que se va a ejecutar.
SqlParameters dynamic Objeto contenedor de propiedades que se va a pasar como parámetros junto con la consulta. Los nombres de parámetro deben comenzar por @.
OutputSchema Nombres y tipos de las columnas esperadas de la salida del cosmosdb_sql_request complemento. Use la sintaxis siguiente: ( ColumnName : ColumnType [, ...] ). Al especificar este parámetro se habilitan varias optimizaciones de consulta.
Opciones dynamic Objeto de contenedor de propiedades de la configuración avanzada. Si no se proporciona en AccountKey ConnectionString, se requiere el armResourceId campo de este parámetro. Para obtener más información, consulte Opciones admitidas.

Opciones admitidas

En la tabla siguiente se describen los campos admitidos del parámetro Options .

Nombre Escribir Descripción
armResourceId string Identificador de recurso de Azure Resource Manager de la base de datos de Cosmos DB. Si no se proporciona una clave de cuenta en el argumento cadena de conexión, este campo es obligatorio. En tal caso, armResourceId se usa para autenticarse en Cosmos DB.
Ejemplo: armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'
token string Un token de acceso de Microsoft Entra de una entidad de seguridad con acceso a la base de datos de Cosmos DB. Este token se usa junto con armResourceId para autenticarse con Azure Resource Manager. Si no se especifica, se usa el token de la entidad de seguridad que realizó la consulta.

Si armResourceId no se especifica, el token se usa directamente para acceder a la base de datos de Cosmos DB. Para obtener más información sobre el método de autenticación de tokens, consulte Autenticación y autorización.
preferredLocations string Región desde la que se van a consultar los datos.
Ejemplo: ['East US']

Autenticación y autorización

Para autorizar a un punto de conexión de red de SQL de Azure Cosmos DB, debe especificar la información de autorización. En la tabla siguiente se proporcionan los métodos de autenticación admitidos y la descripción de cómo usar ese método.

Método de autenticación Descripción
Identidad administrada (recomendada) Anexe Authentication="Active Directory Managed Identity";User Id={object_id}; al cadena de conexión. La solicitud se realiza en nombre de una identidad administrada que debe tener los permisos adecuados para la base de datos.
Para habilitar la autenticación de identidad administrada, debe agregar la identidad administrada al clúster y modificar la directiva de identidad administrada. Para más información, consulte Directiva de identidad administrada.
El identificador de recursos de Azure Resource Manager Este método de autenticación requiere especificar y armResourceId , opcionalmente, en token las opciones. armResourceId identifica la cuenta de base de datos de Cosmos DB y token debe ser un token de portador de Microsoft Entra válido para una entidad de seguridad con permisos de acceso a la base de datos de Cosmos DB. Si no se proporciona, token el token de Microsoft Entra de la entidad de seguridad solicitante se usará para la autenticación.
Clave de cuenta Puede agregar la clave de cuenta directamente al argumento ConnectionString . Sin embargo, este enfoque es menos seguro, ya que implica incluir el secreto en el texto de la consulta y es menos resistente a los cambios futuros en la clave de cuenta. Para mejorar la seguridad, oculte el secreto como un literal de cadena ofuscado.
Token Puede agregar un valor de token en las opciones del complemento. El token debe pertenecer a una entidad de seguridad con permisos pertinentes. Para mejorar la seguridad, oculte el token como un literal de cadena ofuscado.

Establecimiento de la directiva de llamada

El complemento realiza llamadas a la instancia de Azure Cosmos DB. Asegúrese de que la directiva de llamada del clúster habilita las llamadas de tipo cosmosdb al CosmosDbUri de destino.

En el ejemplo siguiente se muestra cómo definir la directiva de llamada para Azure Cosmos DB. Se recomienda restringirlo a puntos de conexión 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
  }
]

En el ejemplo siguiente se muestra un comando alter callout policy para cosmosdb CalloutType.

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

Ejemplos

En los ejemplos siguientes se usa texto de marcador de posición, entre corchetes.

Consulta de Azure Cosmos DB con un esquema de salida definido por consultas

En el ejemplo siguiente se usa el complemento cosmosdb_sql_request para enviar una consulta SQL al seleccionar solo columnas específicas. Esta consulta usa definiciones de esquema explícitas que permiten varias optimizaciones antes de que se ejecute la consulta real en 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)

Consulta de Azure Cosmos DB

En el ejemplo siguiente se usa el complemento cosmosdb_sql_request para enviar una consulta SQL para capturar datos de Azure Cosmos DB mediante su instancia de 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.

Consulta de Azure Cosmos DB con parámetros

En el ejemplo siguiente se usan parámetros de consulta SQL y se consultan los datos de una región alternativa. Para obtener más información, vea 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'

Consulta de Azure Cosmos DB y combinación de datos con una tabla de base de datos

En el ejemplo siguiente se unen los datos de asociados de una instancia de Azure Cosmos DB con los datos de asociados de una base de datos mediante el Partner campo . Da como resultado una lista de asociados con sus números de teléfono, sitio web y dirección de correo electrónico de contacto ordenadas por nombre de asociado.

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

Consulta de Azure Cosmos DB mediante la autenticación de tokens

En el ejemplo siguiente se unen los datos de asociados de una instancia de Azure Cosmos DB con los datos de asociados de una base de datos mediante el Partner campo . Da como resultado una lista de asociados con sus números de teléfono, sitio web y dirección de correo electrónico de contacto ordenadas por nombre de asociado.

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)

Consulta de Azure Cosmos DB mediante el identificador de recurso de Azure Resource Manager para la autenticación

En el ejemplo siguiente se usa el identificador de recurso de Azure Resource Manager para la autenticación y el token de Microsoft Entra de la entidad de seguridad solicitante, ya que no se especifica un token. Envía una consulta SQL al seleccionar solo columnas específicas y especifica definiciones 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)