cosmosdb_sql_request 플러그인

플러그 인은 cosmosdb_sql_request SQL 쿼리를 Azure Cosmos DB SQL 네트워크 엔드포인트로 보내고 쿼리 결과를 반환합니다. 이 플러그 인은 주로 Azure Cosmos DB에 저장된 참조 데이터를 사용하여 데이터를 보강하는 등 작은 데이터 세트를 쿼리하기 위해 설계되었습니다. 플러그 인은 연산자를 사용하여 호출됩니다 evaluate .

Syntax

evaluatecosmosdb_sql_request(Connectionstring,SqlQuery [,SqlParameters [,옵션]] ) [:OutputSchema]

구문 규칙에 대해 자세히 알아보세요.

매개 변수

이름	형식	필수	Description
ConnectionString	string	✔️	쿼리할 Azure Cosmos DB 컬렉션을 가리키는 연결 문자열. AccountEndpoint, Database 및 Collection을 포함해야 합니다. master 키가 인증에 사용되는 경우 AccountKey를 포함할 수 있습니다. 자세한 내용은 인증 및 권한 부여를 참조하세요. 예제:'AccountEndpoint=https://cosmosdbacc.documents.azure.com/ ;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;'
SqlQuery	string	✔️	실행할 쿼리입니다.
SqlParameters	dynamic		쿼리와 함께 매개 변수로 전달할 속성 모음 개체입니다. 매개 변수 이름은 로 @시작해야 합니다.
OutputSchema			플러그 인 출력의 예상 열 cosmosdb_sql_request 이름 및 형식입니다. ColumnName:ColumnType [, ...] )구문을 ( 사용합니다. 이 매개 변수를 지정하면 여러 쿼리 최적화가 가능합니다.
옵션	dynamic		고급 설정의 속성 모음 개체입니다. AccountKeyConnectionStringarmResourceId에 가 제공되지 않으면 이 매개 변수의 필드가 필요합니다. 자세한 내용은 지원되는 옵션을 참조하세요.

지원되는 옵션

다음 표에서는 Options 매개 변수의 지원되는 필드에 대해 설명합니다.

Name	형식	Description
armResourceId	string	Cosmos DB 데이터베이스의 Azure Resource Manager 리소스 ID입니다. 연결 문자열 인수에 계정 키가 제공되지 않으면 이 필드가 필요합니다. 이러한 경우 armResourceId 는 Cosmos DB에 인증하는 데 사용됩니다. 예제:/subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbacc
token	string	Cosmos DB 데이터베이스에 대한 액세스 권한이 있는 보안 주체의 Microsoft Entra 액세스 토큰입니다. 이 토큰은 와 armResourceId 함께 Azure Resource Manager 인증하는 데 사용됩니다. 지정되지 않은 경우 쿼리를 만든 보안 주체의 토큰이 사용됩니다.
preferredLocations	string	데이터를 쿼리할 지역입니다. 예제:['East US']

인증 및 권한 부여

Azure Cosmos DB SQL 네트워크 엔드포인트에 권한을 부여하려면 권한 부여 정보를 지정해야 합니다. 다음 표에서는 지원되는 인증 방법과 해당 메서드를 사용하는 방법에 대한 설명을 제공합니다.

인증 방법	Description
Azure Resource Manager 리소스 ID(권장)	보안 인증의 경우 옵션에서 및 를 선택적으로 token 지정하는 armResourceId 것이 좋습니다. 는 armResourceId Cosmos DB 데이터베이스 계정을 식별하고, token 는 Cosmos DB 데이터베이스에 대한 액세스 권한이 있는 보안 주체에 대한 유효한 Microsoft Entra 전달자 토큰이어야 합니다. 이 제공되지 token 않으면 요청 보안 주체의 Microsoft Entra 토큰이 인증에 사용됩니다.
계정 키	계정 키를 ConnectionString 인수에 직접 추가할 수 있습니다. 그러나 이 방법은 쿼리 텍스트에 비밀을 포함하므로 안전하지 않으며 계정 키의 향후 변경에 대한 복원력이 떨어집니다. 보안을 강화하려면 비밀을 난독 처리를 한 문자열 리터럴로 숨깁니다.

콜아웃 정책 설정

플러그 인은 Azure Cosmos DB instance 설명합니다. 클러스터의 설명선 정책에서 대상 CosmosDbUri에 대한 형식 cosmosdb 호출을 사용하도록 설정해야 합니다.

다음 예제에서는 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
  }
]

다음 예제에서는 CalloutType에 대한 cosmosdb 설명선 변경 정책 명령을 보여줍니다.

.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 플러그 인을 사용하여 Azure Cosmos DB for NoSQL을 사용하여 Azure Cosmos DB에서 데이터를 가져오는 SQL 쿼리를 보냅니다.

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에서 지원되지 않습니다.