解析器的 HTTP 資料來源

  • 發行項

適用於：所有 API 管理 層

http-data-source 解析器原則會設定 HTTP 要求，並選擇性地設定 HTTP 回應，以解析 GraphQL 結構描述中物件類型和欄位的資料。 您必須將這個結構描述匯入 APIM 當作圖形 API。

注意

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

原則陳述式

<http-data-source> 
    <http-request>
        <get-authorization-context>...get-authorization-context policy configuration...</get-authorization-context>
        <set-backend-service>...set-backend-service policy configuration...</set-backend-service>
        <set-method>...set-method policy configuration...</set-method> 
        <set-url>URL</set-url>
        <include-fragment>...include-fragment policy configuration...</include-fragment>
        <set-header>...set-header policy configuration...</set-header>
        <set-body>...set-body policy configuration...</set-body>
        <authentication-certificate>...authentication-certificate policy configuration...</authentication-certificate>  
    </http-request> 
    <backend>
        <forward-request>...forward-request policy configuration...</forward-request>
    <http-response>
        <set-body>...set-body policy configuration...</set-body>
        <xml-to-json>...xml-to-json policy configuration...</xml-to-json>
        <find-and-replace>...find-and-replace policy configuration...</find-and-replace>
        <publish-event>...publish-event policy configuration...</publish-event>
        <include-fragment>...include-fragment policy configuration...</include-fragment>
    </http-response>
</http-data-source>

元素

名稱 描述 必要
http-request 指定 URL 和子原則，以設定解析器的 HTTP 要求。 Yes
後端 可將解析器的 HTTP 要求轉接到後端服務（如果指定的話）。 No
http-response 選擇性指定子原則以設定解析器的 HTTP 回應。 如未指定，則會以原始字串的形式傳回回應。 No

http-request 元素

注意

除非有註明，否則每個子項目最多只能指定一次。 依序指定元素。

元素 描述 必要
get-authorization-context 取得解析器 HTTP 要求的授權內容。 No
set-backend-service 將解析器的 HTTP 要求，重新導向指定的後端。 No
include-fragment 在原則定義中插入原則片段。 如果有多個片段，請新增其他 include-fragment 元素。 No
set-method 設定解析器 HTTP 要求的方法。 Yes
set-url 設定解析器 HTTP 要求的 URL。 Yes
set-header 設定解析器 HTTP 要求的標頭。 如果有多個標頭，請新增其他 header 元素。 No
set-body 設定解析器 HTTP 要求中的內文。 No
authentication-certificate 使用解析器 HTTP 要求中的用戶端憑證進行驗證。 No

後端元素

元素 描述 必要
forward-request 將解析器的 HTTP 要求轉接到後端服務。 No

http-response 元素

注意

除非有註明，否則每個子項目最多只能指定一次。 依序指定元素。

名稱 描述 必要
set-body 設定解析器 HTTP 回應中的內文。 No
xml-to-json 將解析器的 HTTP 回應，從 XML 轉換成 JSON。 No
find-and-replace 在解析器的 HTTP 回應中尋找 substring，並以不同的 substring 取代。 No
publish-event 將事件發佈到 GraphQL API 結構描述中指定的一或多個訂用帳戶。 No
include-fragment 在原則定義中插入原則片段。 如果有多個片段，請新增其他 include-fragment 元素。 No

使用方式

使用注意事項

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

範例

GraphQL 查詢的解析器

下列範例會對後端資料來源發出 HTTP GET 呼叫，以解析查詢。

範例結構描述

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

範例原則

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>https://data.contoso.com/get/users</set-url>
    </http-request>
</http-data-source>

使用 liquid 範本傳回清單的 GraqhQL 查詢解析器

下列範例會使用 set-body 原則支援使用的 liquid 範本，在查詢的 HTTP 回應中傳回清單。 也會在 GraphQL 回應中，將 REST API 回應中的 username 欄位重新命名為 name。

範例結構描述

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

範例原則

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>https://data.contoso.com/users</set-url>
    </http-request>
    <http-response>
        <set-body template="liquid">
            [
                {% JSONArrayFor elem in body %}
                    {
                        "name": "{{elem.username}}"
                    }
                {% endJSONArrayFor %}
            ]
        </set-body>
    </http-response>
</http-data-source>

GraphQL 變動的解析器

下列範例會對 HTTP 資料來源提出 POST 要求，以解析插入資料的變動。 在 HTTP 要求的 set-body 原則中，原則運算式會修改在 GraphQL 查詢中傳遞為本文的 name 引數。 所傳送的本文看起來會像下列 JSON：

{
    "name": "the-provided-name"
}

範例結構描述

type Query {
    users: [User]
}

type Mutation {
    makeUser(name: String!): User
}

type User {
    id: String!
    name: String!
}

範例原則

<http-data-source>
    <http-request>
        <set-method>POST</set-method>
        <set-url>https://data.contoso.com/user/create </set-url>
        <set-header name="Content-Type" exists-action="override">
            <value>application/json</value>
        </set-header>
        <set-body>@{
            var args = context.GraphQL.Arguments;  
            JObject jsonObject = new JObject();
            jsonObject.Add("name", args["name"])
            return jsonObject.ToString();
        }</set-body>
    </http-request>
</http-data-source>

GraphQL 等位類型的解析程式

下列範例會藉由對後端數據源進行 HTTP GET 呼叫來解析orderById查詢，並傳回包含客戶標識碼和類型的 JSON 物件。 客戶類型是和 GuestCustomer 類型的聯集RegisteredCustomer。

範例結構描述

type Query {
  orderById(orderId: Int): Order
}

type Order {
  customerId: Int!
  orderId: Int!  
  customer: Customer
}

enum AccountType {
  Registered
  Guest
}

union Customer = RegisteredCustomer | GuestCustomer

type RegisteredCustomer {
  accountType: AccountType!
  customerId: Int!
  customerGuid: String!
  firstName: String!
  lastName: String!
  isActive: Boolean!
}

type GuestCustomer {
  accountType: AccountType!
  firstName: String!
  lastName: String!
}

範例原則

在此範例中，我們會模擬來自外部來源的客戶結果，並將擷取的結果硬式編碼在原則中 set-body 。 欄位 __typename 可用來判斷客戶的類型。

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>https://data.contoso.com/orders/</set-url>
    </http-request>
    <http-response>
        <set-body>{"customerId": 12345, "accountType": "Registered", "__typename": "RegisteredCustomer" }
        </set-body>
    </http-response>
</http-data-source>

相關內容

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