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

Подключаемый 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. Если не указано, используется маркер субъекта, который сделал запрос.
preferredLocations	string	Регион, из которого требуется запросить данные. Пример: ['East US']

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

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

Authentication method	Description
Идентификатор ресурса 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 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",
    armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'
) : (Id:long, Name:string, City:string)

Эта возможность не поддерживается в Azure Monitor