共用方式為


解析器的 HTTP 資料來源

適用於:所有 APIM 層

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 查詢的解析器

下列範例會對後端資料來源發出 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 物件。 客戶類型是 RegisteredCustomerGuestCustomer 類型的聯集。

範例結構描述

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>

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