共用方式為


解析器的 Cosmos DB 資料來源

適用於:開發人員 | 基本 | 基本 v2 | 標準 | 標準 v2 | 進階

cosmosdb-data-source 解析器原則會使用 Cosmos DB 資料來源,解析 GraphQL 結構描述中物件類型和欄位的資料。 您必須將這個結構描述匯入 APIM 作為 GraphQL API。

使用此原則可設定單一查詢要求、讀取要求、刪除要求或寫入要求,以及來自 Cosmos DB 資料來源的選擇性回應。

注意

此原則處於預覽狀態。 目前,API 管理的取用層不支援此原則。

注意

請依照原則陳述式中提供的順序,來設定原則的元素和子元素。 深入了解如何設定或編輯 APIM 原則

原則陳述式

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

元素

名稱 描述 必要
connection-info 指定 Cosmos DB 資料庫中容器的連線。 Yes
query-request 指定 Cosmos DB 容器的查詢要求設定。 設定 query-requestread-requestdelete-requestwrite-request 的其中一項
read-request 指定 Cosmos DB 容器的讀取要求設定。 設定 query-requestread-requestdelete-requestwrite-request 的其中一項
delete-request 指定 Cosmos DB 容器的刪除要求設定。 設定 query-requestread-requestdelete-requestwrite-request 的其中一項
write-request 指定 Cosmos DB 容器的寫入要求設定。 設定 query-requestread-requestdelete-requestwrite-request 的其中一項
response 選擇性指定子原則以設定解析器的回應。 如果未指定,則會以 JSON 的形式從 Cosmos DB 傳回回應。 No

connection-info 元素

名稱 描述 必要
connection-string 指定 Cosmos DB 帳戶的連接字串。 如果已設定 APIM 受控識別,請省略帳戶金鑰。 Yes
database-name 字串。 Cosmos DB 資料庫的名稱。 Yes
container-name 字串。 Cosmos DB 資料庫中的容器名稱。 Yes

connection-string 屬性

屬性 描述 是必要欄位 預設
use-managed-identity 布林值。 指定是否要使用 APIM 執行個體的系統指派受控識別來連線到 Cosmos DB 帳戶,以取代連接字串中的帳戶金鑰。 必須設定身分識別才能存取 Cosmos DB 容器。 No false

query-request 屬性

屬性 描述 是必要欄位 預設
enable-low-precision-order-by 布林值。 指定是否要在 Cosmos DB 服務中啟用 EnableLowPrecisionOrderBy 查詢要求屬性。 No N/A

query-request 元素

名稱 描述 必要
sql-statement 查詢要求的 SQL 陳述式。 No
parameters 參數子元素中查詢要求的查詢參數清單。 No
partition-key Cosmos DB 分割區索引鍵,用來將查詢路由傳送至容器中的位置。 No
paging 指定要將查詢結果分割成多個頁面的設定。 No

參數屬性

屬性 描述 是必要欄位 預設
NAME 字串。 以 @ 標記法表示的參數名稱。 Yes N/A

paging 元素

名稱 描述 必要
max-item-count 指定查詢傳回的項目數上限。 如果您不想限制每個查詢執行的結果數,請設定為 -1。 Yes
continuation-token 指定要附加至查詢以取得下一組結果的接續權杖 Yes

max-item-count 屬性

屬性 描述 是必要欄位 預設
template 用來設定 max-item-count 的範本化模式。 目前唯一支援的值為:

- liquidmax-item-count 原則會使用 Liquid 範本化引擎。
No N/A

continuation-token 屬性

屬性 描述 是必要欄位 預設
template 用來設定接續權杖的範本化模式。 目前唯一支援的值為:

- liquid:接續權杖會使用 Liquid 範本化引擎。
No N/A

read-request 元素

名稱 描述 必要
id 容器中所要讀取項目的識別碼。 Yes
partition-key 容器中項目位置的分割區索引鍵。 如果使用 id 指定,則會啟用容器中項目的快速點讀取 (索引鍵/值查閱)。 No

delete-request 屬性

屬性 描述 是必要欄位 預設
consistency-level 字串。 設定刪除要求的 Cosmos DB 一致性層級 No N/A
pre-trigger 字串。 在 Cosmos DB 容器中註冊的預先觸發程序函式的識別碼。 No N/A
post-trigger 字串。 在 Cosmos DB 容器中註冊的後置觸發程序函式的識別碼。 No N/A

delete-request 元素

名稱 描述 必要
id 容器中所要刪除項目的識別碼。 Yes
partition-key 容器中項目位置的分割區索引鍵。 No
etag 容器中項目的實體標記,用於開放式同步存取控制 No

write-request 屬性

屬性 描述 是必要欄位 預設
type 寫入要求的類型:insertreplaceupsert No upsert
consistency-level 字串。 設定寫入要求的 Cosmos DB 一致性層級 No N/A
indexing-directive 決定容器的項目應如何編製索引的編製索引原則 No default
pre-trigger 字串。 在 Cosmos DB 容器中註冊的預先觸發程序函式的識別碼。 No N/A
post-trigger 字串。 在 Cosmos DB 容器中註冊的後置觸發程序函式的識別碼。 No N/A

write-request 元素

名稱 描述 必要
id 容器中項目的識別碼。 typereplace,則為必要。
etag 容器中項目的實體標記,用於開放式同步存取控制 No
set-body 設定寫入要求中的本文。 如果未提供,要求承載會將引數對應至 JSON 格式。 No

response 元素

名稱 描述 必要
set-body 設定解析器回應中的本文。 如果未提供,且傳回的 JSON 包含 GraphQL 結構描述中相符欄位的欄位名稱,則會自動對應欄位。 No
publish-event 將事件發佈到 GraphQL API 結構描述中指定的一或多個訂用帳戶。 No

partition-key 屬性

屬性 描述 是必要欄位 預設
data-type 分割區索引鍵的資料類型:stringnumberboolnonenull No string
template 用來設定分割區索引鍵的範本化模式。 目前唯一支援的值為:

- liquid:分割區索引鍵會使用 Liquid 範本化引擎
No N/A

etag 屬性

屬性 描述 是必要欄位 預設
type 字串。 下列其中一個值:

- matchetag 值必須符合項目系統產生的實體標記

- no-matchetag 值不一定要符合項目系統產生的實體標記
No match
template 用來設定 etag 的範本化模式。 目前唯一支援的值為:

- liquid:etag 會使用 Liquid 範本化引擎
No N/A

使用方式

使用量注意事項

  • 若要使用這個原則設定及管理解析器,請參閱設定 GraphQL 解析器
  • 只有在結構描述的相符作業類型中解析單一欄位時,才會叫用此原則。

設定受控識別與 Cosmos DB 的整合

您可以設定 APIM 系統指派的受控識別來存取 Cosmos DB 帳戶,而不是在連接字串中提供帳戶金鑰。

請遵循下列步驟,使用 Azure CLI 來設定受控識別。

必要條件

用來設定受控識別的 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 帳戶的連線會使用 APIM 執行個體的系統指派受控識別。 必須設定身分識別才能存取 Cosmos DB 容器。

用於讀取要求的 idpartition-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 變動。 用於刪除要求的 idpartition-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 帳戶的連線會使用 APIM 執行個體的系統指派受控識別。 必須設定身分識別才能存取 Cosmos DB 容器。

用於寫入要求的 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 } 
        } 
    }"
}    

從運算式傳遞 JSON 物件 (JObject)

範例原則

[...]
<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>
[...]

從運算式傳遞 JSON 值 (JValue)

範例原則

[...]
<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>
[...]

如需使用原則的詳細資訊,請參閱: