해결 프로그램을 위한 Cosmos DB 데이터 원본

적용 대상: 개발자 | 기본 | 기본 v2 | 표준 | 표준 v2 | 프리미엄 | 프리미엄 v2

cosmosdb-data-source 해결 프로그램 정책은 Cosmos DB 데이터 원본을 사용하여 GraphQL 스키마의 개체 형식 및 필드에 대한 데이터를 확인합니다. 스키마는 GraphQL API로 API Management에 가져와야 합니다.

정책을 사용하여 단일 쿼리 요청, 읽기 요청, 삭제 요청 또는 쓰기 요청 및 Cosmos DB 데이터 원본의 선택적 응답을 구성합니다.

정책 문

<cosmosdb-data-source> 
    <!-- Required information that specifies connection to Cosmos DB -->
    <connection-info> 
        <connection-string use-managed-identity="true | false"> 
            AccountEndpoint=...;[AccountKey=...;]
        </connection-string> 
        <database-name>Cosmos DB database name</database-name> 
        <container-name>Name of container in Cosmos DB database</container-name>     
    </connection-info>

    <!-- Settings to query using a SQL statement and optional query parameters -->
    <query-request enable-low-precision-order-by="true | false"> 
        <sql-statement> 
            SQL statement 
        </sql-statement> 
        <parameters> 
            <parameter name="Query parameter name in @ notation"> 
                "Query parameter value or expression"
            </parameter>
            <!-- if there are multiple parameters, then add additional parameter elements --> 
        </parameters> 
        <partition-key data-type="string | number | bool | none | null" template="liquid" > 
            "Container partition key" 
        </partition-key> 
        <paging> 
            <max-item-count template="liquid" > 
                Maximum number of items returned by query
            </max-item-count> 
            <continuation-token template="liquid"> 
                Continuation token for paging 
            </continuation-token> 
        </paging>
    </query-request>
    
    <!-- Settings to read item by item ID and optional partition key --> 
    <read-request> 
        <id template="liquid" >
            "Item ID in container"
        </id> 
        <partition-key data-type="string | number | bool | none | null" template="liquid" > 
            "Container partition key" 
        </partition-key>  
    </read-request> 
    
    <!-- Settings to delete item by ID and optional partition key --> 
    <delete-request consistency-level="bounded-staleness | consistent-prefix | eventual | session | strong" pre-trigger="myPreTrigger" post-trigger="myPostTrigger">
        <etag type="entity tag type" template="liquid" > 
            "System-generated entity tag" 
        </etag> 
        <id template="liquid">
            "Item ID in container"
        </id> 
        <partition-key data-type="string | number | bool | none | null" template="liquid"> 
            "Container partition key" 
        </partition-key> 
    </delete-request> 
    
    <!-- Settings to write item -->
    <write-request type="insert | replace | upsert" consistency-level="bounded-staleness | consistent-prefix | eventual | session | strong" pre-trigger="myPreTrigger" post-trigger="myPostTrigger">
        <id template="liquid">
            "Item ID in container"
        </id>
         <partition-key data-type="string | number | bool | none | null" template="liquid"> 
            "Container partition key"
        </partition-key>      
        <etag type="match | no-match" template="liquid" > 
            "System-generated entity tag" 
        </etag>
        <set-body template="liquid" >...set-body policy configuration...</set-body> 
    </write-request>
    
    <response> 
        <set-body>...set-body policy configuration...</set-body> 
        <publish-event>...publish-event policy configuration...</publish-event>
    </response>
    
</cosmosdb-data-source> 

Elements

connection-info 요소

connection-string 특성

query-request 특성

query-request 요소

parameter 특성

paging 요소

max-item-count attribute

continuation-token 특성

read-request 요소

delete-request 특성

delete-request 요소

write-request 특성

write-request 요소

response 요소

partition-key 특성

etag 특성

사용

• 정책 범위: GraphQL 해결 프로그램
• 게이트웨이: 클래식, v2

사용법 참고 사항

• 이 정책을 사용하여 해결 프로그램을 구성하고 관리하려면 GraphQL 해결 프로그램 구성을 참조하세요.
• 이 정책은 스키마의 일치하는 작업 형식에서 단일 필드를 확인할 때만 호출됩니다.

Cosmos DB와 관리 ID의 통합 구성

Cosmos DB 계정에 액세스하는 데 연결 문자열의 계정 키를 제공하는 대신 API Management 시스템이 할당한 관리 ID를 구성할 수 있습니다.

다음 단계에 따라 Azure CLI를 사용하여 관리 ID를 구성합니다.

필수 조건

• API Management 인스턴스에서 시스템 할당 관리 ID를 사용하도록 설정합니다. 포털에서 관리 ID의 개체(보안 주체) ID를 적어 둡니다.

• • Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.

    

  • CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.

    • 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.

    • 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.

    • az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

관리 ID를 구성하는 Azure CLI 스크립트

# Set variables

# Variable for Azure Cosmos DB account name
cosmosName="<MY-COSMOS-DB-ACCOUNT>"

# Variable for resource group name
resourceGroupName="<MY-RESOURCE-GROUP>"

# Variable for subscription
resourceGroupName="<MY-SUBSCRIPTION-NAME>"

# Set principal variable to the value from Managed identities page of API Management instance in Azure portal
principal="<MY-APIM-MANAGED-ID-PRINCIPAL-ID>"

# Get the scope value of Cosmos DB account
 
scope=$(
    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $cosmosName \
        --subscription $subscriptionName \
        --query id \
        --output tsv
)

# List the built-in Cosmos DB roles
# Currently, the roles aren't visible in the portal

az cosmosdb sql role definition list \
    --resource-group $resourceGroupName \
    --account-name $cosmosName \
    --subscription $subscriptionName \

# Take note of the role you want to assign, such as "Cosmos DB Built-in Data Contributor" in this example

# Assign desired Cosmos DB role to managed identity

az cosmosdb sql role assignment create \
    --resource-group $resourceGroupName \
    --account-name $cosmosName \
    --subscription $subscriptionName \
    --role-definition-name "Cosmos DB Built-in Data Contributor" \
    --principal-id $principal \
    --scope $scope    

예제

Cosmos DB 쿼리 요청

다음 예제에서는 Cosmos DB 컨테이너에 대한 SQL 쿼리를 사용하여 GraphQL 쿼리를 해결합니다.

<cosmosdb-data-source>
    <connection-info>
        <connection-string>
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;AccountKey=CONTOSOKEY;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <query-request>
        <sql-statement>SELECT * FROM c </sql-statement>
    </query-request>
</cosmosdb-data-source>

Cosmos DB 읽기 요청

다음 예제에서는 Cosmos DB 컨테이너에 대한 지점 읽기 요청을 사용하여 GraphQL 쿼리를 해결합니다. Cosmos DB 계정에 대한 연결은 API Management 인스턴스의 시스템이 할당한 관리 ID를 사용합니다. Cosmos DB 컨테이너에 액세스하도록 ID를 구성해야 합니다.

읽기 요청에 사용되는 id과(와) partition-key은(는) 쿼리 매개 변수로 전달되고 context.GraphQL.Arguments["id"] 컨텍스트 변수를 사용하여 액세스됩니다.

<cosmosdb-data-source>
    <connection-info>
        <connection-string use-managed-identity="true">
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <read-request>
        <id>
            @(context.GraphQL.Arguments["id"].ToString())
        </id>
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
    <read-request>
</cosmosdb-data-source>

Cosmos DB 삭제 요청

다음 예제에서는 Cosmos DB 컨테이너에 대한 삭제 요청으로 GraphQL 변형을 해결합니다. 삭제 요청에 사용되는 id과(와) partition-key은(는) 쿼리 매개 변수로 전달되고 context.GraphQL.Arguments["id"] 컨텍스트 변수를 사용하여 액세스됩니다.

<cosmosdb-data-source>
    <connection-info>
        <connection-string>
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;AccountKey=CONTOSOKEY;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <delete-request>
        <id>
            @(context.GraphQL.Arguments["id"].ToString())
        </id>
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
        </partition-key>
    </delete-request>
</cosmosdb-data-source>

Cosmos DB 쓰기 요청

다음 예제에서는 Cosmos DB 컨테이너에 대한 upsert 요청으로 GraphQL 변형을 해결합니다. Cosmos DB 계정에 대한 연결은 API Management 인스턴스의 시스템이 할당한 관리 ID를 사용합니다. Cosmos DB 컨테이너에 액세스하도록 ID를 구성해야 합니다.

쓰기 요청에 사용되는 partition-key은(는) 쿼리 매개 변수로 전달되고 컨텍스트 변수를 context.GraphQL.Arguments["id"] 사용하여 액세스됩니다. upsert 요청에는 "validateInput"이라는 사전 트리거 작업이 있습니다. 요청 본문은 liquid 템플릿을 사용하여 매핑됩니다.

<cosmosdb-data-source>
    <connection-info>
        <connection-string use-managed-identity="true">
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <write-request type="upsert" pre-trigger="validateInput">
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
        </partition-key>
        <set-body template="liquid">
            {"id" : "{{body.arguments.id}}" ,
            "firstName" : "{{body.arguments.firstName}}",
            "intField" : {{body.arguments.intField}} ,
            "floatField" : {{body.arguments.floatField}} ,
            "boolField" : {{body.arguments.boolField}}}
        </set-body>
    </write-request>
</cosmosdb-data-source>

Cosmos DB 쿼리에 대한 매개 변수 입력 생성

다음 예제에서는 정책 식을 사용하여 Cosmos DB 매개 변수화된 쿼리를 생성하는 방법을 보여줍니다. 매개 변수 입력의 형식에 따라 메서드를 선택합니다.

예제는 다음 샘플 GraphQL 스키마를 기반으로 하며, 상응하는 Cosmos DB 매개 변수화된 쿼리를 생성합니다.

예제 GraphQL 스키마

input personInput {
  id: String!
  firstName: String
}

type Query {
  personsStringParam(stringInput: String): personsConnection
  personsPersonParam(input: personInput): personsConnection
}

예제 Cosmos DB 쿼리

{
    "query": "query { 
        personsPersonParam(input: { id: \"3\" } { 
        items { id firstName lastName } 
        } 
    }"
}    

식에서 JObject(JSON 개체) 전달

예제 정책

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param.id</sql-statement>
    <parameters>
        <parameter name="@param">@(context.GraphQL.Arguments["input"])</parameter>
    </parameters>
    </query-request>
[...]

식에서 .NET 입력 형식(string, int, decimal, bool) 전달

예제 정책

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param</sql-statement>
    <parameters>
        <parameter name="@param">@($"start.{context.GraphQL.Arguments["stringInput"]}")</parameter>
    </parameters>
</query-request>
[...]

식에서 JValue(JSON 값) 전달

예제 정책

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param</sql-statement>
    <parameters>
        <parameter name="@param">@(context.GraphQL.Arguments["stringInput"])</parameter>
    </parameters>
</query-request>
[...]

관련 정책

• GraphQL 확인자

관련 콘텐츠

정책 작업에 대한 자세한 내용은 다음을 참조하세요.

• 자습서: API 변환 및 보호
• 정책 문 및 해당 설정에 대한 전체 목록에 대한 정책 참조
• 정책 식
• 정책 설정 또는 편집
• 정책 구성 재사용
• 정책 코드 조각 리포지토리
• Azure API Management 정책 도구 키트
• Azure의 Microsoft Copilot을 사용하는 작성자 정책