SetOAuthV2Info 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

可讓您新增或更新與存取權杖相關聯的自訂屬性。自訂屬性可能包含部門名稱、客戶 ID 或工作階段 ID 等。另請參閱自訂權杖與授權碼

只能新增或修改自訂屬性。您無法使用這項政策變更範圍、status、Expiration_in、developer_email、client_id、org_name 或 refresh_count 等欄位。如果已有屬性,這項政策會更新該屬性。如果沒有,政策會新增該字串。參照的存取權杖必須有效且處於已核准狀態。

範例

基本範例

以下是用於更新 OAuth 2.0 存取權杖的政策範例。以下範例會尋找名為 access_token 的查詢參數,找出要求訊息上的存取權杖。當用戶端應用程式顯示存取權杖時,下列政策會在查詢參數中找出存取權杖。接著會更新存取權杖的設定檔。會在設定檔中新增名為 department.id 的自訂屬性。

<SetOAuthV2Info name="SetOAuthV2Info"> 
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
  <Attributes>
    <Attribute name="department.id" ref="request.queryparam.department_id"></Attribute>
  </Attributes>
</SetOAuthV2Info>

元素參照

元素參考資料說明 SetOAuthV2 政策的元素和屬性。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SetOAuthV2Info async="false" continueOnError="false" enabled="true" name="SetOAuthV2Info-1">    
    <DisplayName>Set OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref={some-variable}></AccessToken>
    <Attributes/>
</SetOAuthV2Info>
</xml>

<SetOAuthV2Info> 屬性

<SetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Set-OAuth-v20-Info-1">

下表說明所有政策父項元素的通用屬性:

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個半形字元。

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

<AccessToken> 元素

指出存取權杖所在的變數。舉例來說,如果存取權杖是以查詢參數的形式附加至要求訊息,請指定 request.queryparam.access_token。您可以使用任何參照權杖的有效變數。或者,也可以傳入常值權杖字串 (罕見大小寫)。

 <AccessToken ref="request.queryparam.access_token"></AccessToken>
預設: 不適用
所在地: 需要
類型: 字串

屬性

屬性 說明 預設 存在必要性
參考資料

存取權杖變數。一般而言,擷取自流程變數。

不適用 選用

<Attributes> 元素

存取權杖設定檔中需要修改或擴充的一組屬性。

預設: 不適用
所在地: 需要
類型: 不適用

<Attributes>/<Attribute> 元素

要更新的個別屬性。

名稱屬性可識別要更新存取權杖設定檔的自訂屬性。本範例說明如何使用參照的變數值和靜態值。

  <Attributes>
    <Attribute name="department.id" ref="request.queryparam.department_id"></Attribute>
    <Attribute name="foo">bar</Attribute>
  </Attributes>
預設: 不適用
所在地: 選用
類型: 不適用

屬性

屬性 說明 預設 存在必要性
名稱 要新增或變更的設定檔屬性名稱。 不適用
參考資料

要指派給設定檔屬性的值。

不適用 選用

流程變數

成功後,將會設定下列流程變數:

  • oauthv2accesstoken.{policyName}.access_token
  • oauthv2accesstoken.{policyName}.client_id
  • oauthv2accesstoken.{policyName}.refresh_count
  • oauthv2accesstoken.{policyName}.organization_name
  • oauthv2accesstoken.{policyName}.expires_in //--in seconds
  • oauthv2accesstoken.{policyName}.refresh_token_expires_in //--in seconds
  • oauthv2accesstoken.{policyName}.issued_at
  • oauthv2accesstoken.{policyName}.status
  • oauthv2accesstoken.{policyName}.api_product_list
  • oauthv2accesstoken.{policyName}.token_type
  • oauthv2accesstoken.{policyName}.{custom_attribute_name}

結構定義

每個政策類型都是由 XML 結構定義 (.xsd) 定義。如需參考,GitHub 提供政策結構定義

錯誤參考資料

本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

執行政策時,可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因
steps.oauth.v2.access_token_expired 500 傳送至政策的存取權杖已過期。
steps.oauth.v2.invalid_access_token 500 傳送至政策的存取權權杖無效。
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 如要瞭解如何排解這項錯誤,請參閱 這篇 Apigee 社群文章

部署錯誤

如要瞭解部署錯誤,請參閱使用者介面中回報的訊息。

錯誤變數

當這項政策在執行階段觸發錯誤時,系統會設定這些變數。

Variables 地點 範例
fault.name="fault_name" fault_name 是錯誤的名稱,如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤碼的最後一個部分。 fault.name = "invalid_access_token"
oauthV2.policy_name.failed policy_name 是擲回錯誤的政策使用者指定的名稱。 oauthV2.SetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name 是擲回錯誤的政策使用者指定的名稱。 oauthV2.SetTokenInfo.fault.name = invalid_access_token
oauthv2.policy_name.fault.cause policy_name 是擲回錯誤的政策使用者指定的名稱。 oauthV2.SetTokenInfo.cause = Invalid Access Token

錯誤回應範例

{
  "fault": {
    "faultstring": "Invalid Access Token",
    "detail": {
      "errorcode": "keymanagement.service.invalid_access_token"
    }
  }
}

故障規則示例

<FaultRule name=SetOAuthV2Info Faults">
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

相關主題