Подключаемый модуль cosmosdb_sql_request

  • Статья

Область применения: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Подключаемый cosmosdb_sql_request модуль отправляет SQL-запрос в конечную точку сети SQL Azure Cosmos DB и возвращает результаты запроса. Этот подключаемый модуль в основном предназначен для запроса небольших наборов данных, например обогащения данных ссылочными данными, хранящимися в Azure Cosmos DB. Подключаемый модуль вызывается оператором evaluate .

Синтаксис

evaluatecosmosdb_sql_request ( ConnectionString SqlQuery [, SqlParameters [, Параметры]] ) [: OutputSchema] ,

Дополнительные сведения о соглашениях синтаксиса.

Параметры

Имя (название) Type Обязательно Описание
ConnectionString string ✔️ Строка подключения, указывающий на коллекцию Azure Cosmos DB для запроса. Он должен включать AccountEndpoint, Базу данных и коллекцию. Он может включать AccountKey , если главный ключ используется для проверки подлинности. Дополнительные сведения см. в разделе "Проверка подлинности и авторизация".
Пример: 'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>'
SqlQuery string ✔️ Выполняемый запрос.
SqlParameters dynamic Объект контейнера свойств для передачи параметров вместе с запросом. Имена параметров должны начинаться с @.
OutputSchema Имена и типы ожидаемых столбцов выходных данных подключаемого cosmosdb_sql_request модуля. Используйте следующий синтаксис: ( ColumnName : ColumnType [, ...] ). Указание этого параметра включает несколько оптимизаций запросов.
Параметры dynamic Объект контейнера свойств расширенных параметров. Если параметр AccountKey не указан в ConnectionString, armResourceId необходимо поле этого параметра. Дополнительные сведения см. в разделе "Поддерживаемые параметры".

Поддерживаемые параметры

В следующей таблице описываются поддерживаемые поля параметра Options .

Имя. Тип Описание
armResourceId string Идентификатор ресурса Azure Resource Manager базы данных Cosmos DB. Если ключ учетной записи не указан в аргументе строка подключения, это поле является обязательным. В таком случае armResourceId используется для проверки подлинности в Cosmos DB.
Пример: armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'
token string Маркер доступа Microsoft Entra субъекта с доступом к базе данных Cosmos DB. Этот маркер используется вместе с armResourceId проверкой подлинности с помощью Azure Resource Manager. Если не указано, используется маркер субъекта, который сделал запрос.

Если armResourceId он не указан, маркер используется непосредственно для доступа к базе данных Cosmos DB. Дополнительные сведения о методе проверки подлинности маркеров см. в разделе "Проверка подлинности и авторизация".
preferredLocations string Регион, из которого требуется запросить данные.
Пример: ['East US']

Проверка подлинности и авторизация

Чтобы авторизовать конечную точку сети SQL Azure Cosmos DB, необходимо указать сведения об авторизации. В следующей таблице приведены поддерживаемые методы проверки подлинности и описание использования этого метода.

Authentication method Description
Управляемое удостоверение (рекомендуется) Добавьте Authentication="Active Directory Managed Identity";User Id={object_id}; к строка подключения. Запрос выполняется от имени управляемого удостоверения, который должен иметь соответствующие разрешения для базы данных.
Чтобы включить проверку подлинности управляемого удостоверения, необходимо добавить управляемое удостоверение в кластер и изменить политику управляемого удостоверения. Дополнительные сведения см. в разделе "Политика управляемого удостоверения".
Идентификатор ресурса Azure Resource Manager Этот метод проверки подлинности требует указания armResourceId и при необходимости token в параметрах. Определяет armResourceId учетную запись базы данных Cosmos DB и token должен быть допустимым маркером носителя Microsoft Entra для субъекта с разрешениями доступа к базе данных Cosmos DB. Если не token указано, маркер Microsoft Entra запрашивающего субъекта будет использоваться для проверки подлинности.
Ключ учетной записи Ключ учетной записи можно добавить непосредственно в аргумент ConnectionString . Однако этот подход является менее безопасным, так как он включает в себя включение секрета в текст запроса и менее устойчив к будущим изменениям в ключе учетной записи. Чтобы повысить безопасность, скрытие секрета в виде закрытого строкового литерала.
Маркер Значение маркера можно добавить в параметры подключаемого модуля. Маркер должен принадлежать субъекту с соответствующими разрешениями. Чтобы повысить безопасность, скрытие маркера в виде запутанного строкового литерала.

Настройка политики выноски

Подключаемый модуль отправляет выноски экземпляру Azure Cosmos DB. Убедитесь, что политика выноски кластера включает вызовы типа cosmosdb в целевой CosmosDbUri.

В следующем примере показано, как определить политику выноски для Azure Cosmos DB. Рекомендуется ограничить его определенными конечными точками (my_endpoint1, my_endpoint2).

[
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint1\\.documents\\.azure\\.com",
    "CanCall": true
  },
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint2\\.documents\\.azure\\.com",
    "CanCall": true
  }
]

В следующем примере показана команда политики изменения выноски для cosmosdb CalloutType

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

Примеры

В следующих примерах используется текст заполнителя в квадратных скобках.

Запрос Azure Cosmos DB с помощью схемы выходных данных, определяемой запросом

В следующем примере используется подключаемый модуль cosmosdb_sql_request для отправки SQL-запроса при выборе только определенных столбцов. Этот запрос использует явные определения схемы, которые позволяют выполнять различные оптимизации перед запуском фактического запроса в 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)

Запрос БД Azure Cosmos DB

В следующем примере используется подключаемый модуль cosmosdb_sql_request для отправки SQL-запроса для получения данных из Azure Cosmos DB с помощью Azure Cosmos DB для 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.

Запрос Azure Cosmos DB с параметрами

В следующем примере используются параметры SQL-запроса и запрашиваются данные из альтернативного региона. Дополнительные сведения см. в разделе 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'

Запрос данных Azure Cosmos DB и присоединение данных к таблице базы данных

В следующем примере данные партнера присоединяются из Azure Cosmos DB с данными партнера в базе данных с помощью Partner поля. Это приводит к тому, что список партнеров со своими номерами телефонов, веб-сайтом и адресом электронной почты, отсортированный по имени партнера.

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

Запрос Azure Cosmos DB с помощью проверки подлинности маркера

В следующем примере данные партнера присоединяются из Azure Cosmos DB с данными партнера в базе данных с помощью Partner поля. Это приводит к тому, что список партнеров со своими номерами телефонов, веб-сайтом и адресом электронной почты, отсортированный по имени партнера.

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)

Запрос Azure Cosmos DB с помощью идентификатора ресурса Azure Resource Manager для проверки подлинности

В следующем примере используется идентификатор ресурса Azure Resource Manager для проверки подлинности и маркер Microsoft Entra субъекта запроса, так как маркер не указан. Он отправляет SQL-запрос при выборе только определенных столбцов и задает явные определения схемы.

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)