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

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

Синтаксис

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

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

Параметры

Имя	Тип	Обязательно	Описание
Connectionstring	string	✔️	Строка подключения, указывающий на коллекцию Azure Cosmos DB для запроса. Он должен включать AccountEndpoint, Database и Collection. Он может включать AccountKey, если для проверки подлинности используется ключ master. Дополнительные сведения см. в разделе Проверка подлинности и авторизация. Примере:'AccountEndpoint=https://cosmosdbacc.documents.azure.com/ ;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;'
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 используется . Примере:/subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbacc
token	string	Microsoft Entra маркер доступа субъекта с доступом к базе данных Cosmos DB. Этот маркер используется вместе с armResourceId для проверки подлинности с помощью Resource Manager Azure. Если этот параметр не указан, используется токен субъекта, который сделал запрос.
preferredLocations	string	Регион, из которого запрашивают данные. Примере:['East US']

Аутентификация и авторизация

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

Метод проверки подлинности	Описание
Идентификатор ресурса 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
  }
]

В следующем примере показана команда alter callout policy для cosmosdbCalloutType

.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'R8PM...;',
  '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'R8PM...;',
  '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'R8PM...;',
    "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 Monitor