cosmosdb_sql_request 플러그 인

아티클
10/15/2024

적용 대상: ✅Microsoft Fabric ✅Azure Data Explorer✅Azure Monitor ✅Microsoft Sentinel

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

구문

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

구문 규칙에 대해 자세히 알아봅니다.

매개 변수

이름	Type	필수	설명
ConnectionString	`string`	✔️	쿼리할 Azure Cosmos DB 컬렉션을 가리키는 연결 문자열. AccountEndpoint, Database 및 Collection을 포함해야 합니다. 마스터 키가 인증에 사용되는 경우 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`	Cosmos DB 데이터베이스의 Azure Resource Manager 리소스 ID입니다. 연결 문자열 인수에 계정 키가 제공되지 않으면 이 필드가 필요합니다. 이러한 경우 `armResourceId` Cosmos DB에 인증하는 데 사용됩니다. 본보기: `armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'`
`token`	`string`	Cosmos DB 데이터베이스에 액세스할 수 있는 보안 주체의 Microsoft Entra 액세스 토큰입니다. 이 토큰은 Azure Resource Manager를 사용하여 인증하는 데 사용됩니다 `armResourceId` . 지정되지 않은 경우 쿼리를 만든 보안 주체의 토큰이 사용됩니다. 지정되지 않은 경우 `armResourceId` 토큰은 Cosmos DB 데이터베이스에 액세스하는 데 직접 사용됩니다. 토큰 인증 방법에 대한 자세한 내용은 인증 및 권한 부여를 참조하세요.
`preferredLocations`	`string`	데이터를 쿼리할 지역입니다. 예: `['East US']`

인증 및 권한 부여

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

인증 방법	설명
관리 ID(권장)	연결 문자열 추가 `Authentication="Active Directory Managed Identity";User Id={object_id};` 합니다. 요청은 데이터베이스에 대한 적절한 권한이 있어야 하는 관리 ID를 대신하여 이루어집니다. 관리 ID 인증을 사용하도록 설정하려면 클러스터에 관리 ID를 추가하고 관리 ID 정책을 변경해야 합니다. 자세한 내용은 관리 ID 정책을 참조하세요.
Azure Resource Manager 리소스 ID	이 인증 방법을 사용하려면 옵션에서 `armResourceId` 선택적으로 `token` 지정해야 합니다. Cosmos `armResourceId` DB 데이터베이스 계정을 식별하며 `token` Cosmos DB 데이터베이스에 대한 액세스 권한이 있는 보안 주체에 대한 유효한 Microsoft Entra 전달자 토큰이어야 합니다. 제공되지 않으면 `token` 요청 주체의 Microsoft Entra 토큰이 인증에 사용됩니다.
계정 키	ConnectionString 인수에 계정 키를 직접 추가할 수 있습니다. 그러나 이 방법은 쿼리 텍스트에 비밀을 포함하므로 안전하지 않으며 계정 키의 향후 변경에 대한 복원력이 떨어집니다. 보안을 강화하려면 비밀을 난독 분석된 문자열 리터럴로 숨깁니다.
토큰	플러그 인 옵션에서 토큰 값을 추가할 수 있습니다. 토큰은 관련 권한이 있는 보안 주체에 속해야 합니다. 보안을 강화하려면 토큰을 난독 분석된 문자열 리터럴로 숨깁니다.

설명선 정책 설정

플러그 인은 Azure Cosmos DB 인스턴스를 설명합니다. 클러스터의 설명선 정책이 대상 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'<AccountKey>',
  'SELECT c.Id, c.Name from c') : (Id:long, Name:string)

Azure Cosmos DB 쿼리

다음 예제에서는 cosmosdb_sql_request 플러그 인을 사용하여 Sql 쿼리를 보내 Azure Cosmos DB for NoSQL을 사용하여 Azure Cosmos DB에서 데이터를 가져옵니다.

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 쿼리 및 데이터베이스 테이블로 데이터 조인

다음 예제에서는 필드를 사용하여 Partner Azure Cosmos DB의 파트너 데이터를 데이터베이스의 파트너 데이터와 조인합니다. 그러면 전화 번호, 웹 사이트 및 연락처 전자 메일 주소가 파트너 이름으로 정렬된 파트너 목록이 생성됩니다.

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 쿼리

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 Resource Manager 리소스 ID를 사용하여 Azure Cosmos DB 쿼리

다음 예제에서는 토큰이 지정되지 않았으므로 인증에 Azure Resource Manager 리소스 ID와 요청 주체의 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)

다음을 통해 공유