解析器的 Cosmos DB 資料來源

適用於：開發人員 |基本 |基本 v2 |標準 |標準 v2 |Premium |進階 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-request、read-request、delete-request 或 write-request 的其中一項
read-request	指定 Cosmos DB 容器的讀取要求設定。	設定 query-request、read-request、delete-request 或 write-request 的其中一項
delete-request	指定 Cosmos DB 容器的刪除要求設定。	設定 query-request、read-request、delete-request 或 write-request 的其中一項
write-request	指定 Cosmos DB 容器的寫入要求設定。	設定 query-request、read-request、delete-request 或 write-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- 使用液體範本化引擎。	No	N/A

continuation-token 屬性

屬性	描述	是必要欄位	預設
template	用來設定接續權杖的範本化模式。 目前唯一支援的值為： - 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	寫入要求的類型：insert、replace 或 upsert。	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	容器中項目的識別碼。	若 type 為 replace，則為必要。
etag	容器中項目的實體標記，用於開放式同步存取控制。	No
set-body	設定寫入要求中的本文。 如果未提供，要求承載會將自變數對應至 JSON 格式。	No

response 元素

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

partition-key 屬性

屬性	描述	是必要欄位	預設
data-type	分割區索引鍵的資料類型：string、number、bool、none 或 null。	No	string
template	用來設定分割區索引鍵的範本化模式。 目前唯一支援的值為： - liquid - 分割區索引鍵使用液體範本化引擎	No	N/A

etag 屬性

屬性	描述	是必要欄位	預設
type	字串。 下列其中一個值： - match：etag 值必須符合項目系統產生的實體標記 - no-match：etag 值不一定要符合項目系統產生的實體標記	No	match
template	用來設定 etag 的範本化模式。 目前唯一支援的值為： - liquid - etag 使用液體範本化引擎	No	N/A

使用方式

• 原則範圍：GraphQL 解析器
• 閘道： 傳統、v2

使用量注意事項

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

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

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

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

必要條件

• 在 APIM 執行個體中啟用系統指派的受控識別。 在入口網站中，記下受控識別的物件 (主體) 識別碼。

• • 在 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。

用來設定受控識別的 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 容器。

用於讀取要求的 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 帳戶的連線會使用 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>
[...]

相關原則

• GraphQL 解析器

相關內容

如需使用原則的詳細資訊，請參閱：

• 教學課程：轉換及保護 API
• 原則參考，取得原則陳述式及其設定的完整清單
• 原則運算式
• 設定或編輯原則
• 重複使用原則設定
• 原則程式碼片段存放庫 (英文)
• Azure API 管理 原則工具組
• 使用 Microsoft Azure Copilot 撰寫原則