本頁面由 Cloud Translation API 翻譯而成。

GetOAuthV2Info 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

取得存取權杖、更新權杖、授權碼和用戶端應用程式屬性，並以這些屬性的值填入變數。

當您需要根據權杖或授權碼中的值設定動態條件式行為時，這項政策就很有用。每當系統驗證權杖時，變數就會自動填入權杖屬性的值。不過，如果尚未驗證權杖，您可以使用這項功能，明確填入權杖的屬性值。另請參閱自訂憑證和授權碼。

傳遞至這項政策的存取權杖必須有效，否則政策會擲回 invalid_access_token 錯誤。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

範例

下列範例會使用「Get OAuth V2 Info」政策，擷取 OAuth2 工作流程各種元件的相關資訊，然後在程式碼中存取該資訊。

存取權杖

如要取得存取權權杖的參照，請在政策中使用 <AccessToken> 元素。

以下範例預期在名為「access_token」的查詢參數中找到存取權杖 (實際的實作詳細資料由您決定)：

<GetOAuthV2Info name="MyTokenAttrsPolicy">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
</GetOAuthV2Info>

有了存取權杖，政策就會查詢權杖的設定檔，並填入一組含有設定檔資料的變數。

然後，您可以使用 JavaScript 或其他方式存取變數。以下範例使用 JavaScript 擷取與存取權杖相關聯的範圍：

var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

請注意，如要在程式碼中存取這些變數，必須加上「oauthv2accesstoken」前置字元。如需透過存取權杖取得的變數完整清單，請參閱「存取權杖變數」。

驗證碼

如要取得授權碼屬性，請在政策中使用 <AuthorizationCode> 元素。

在下列範例中，我們預期會在名為「code」的表單參數中找到存取權杖 (實際的實作詳細資料由您決定)：

<GetOAuthV2Info name="MyAuthCodeAttrsPolicy">
  <AuthorizationCode ref="request.formparam.code"></AuthorizationCode>
</GetOAuthV2Info>

根據授權碼，政策會查詢該授權碼的資訊，並填入一組授權碼資料變數。

然後，您可以使用 JavaScript 或其他方式存取變數。下列範例使用 JavaScript 擷取與授權碼相關聯的自訂屬性：

var attr = context.getVariable('oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name');

請注意，如要在程式碼中存取這些變數，必須加上「oauthv2authcode」前置字元。如需透過授權碼取得的變數完整清單，請參閱「授權碼變數」。

重新整理權杖

如要取得更新權杖屬性，請在政策中使用 <RefreshToken> 元素。

以下範例預期在名為「refresh_token」的查詢參數中找到存取權杖 (實際實作細節由您決定)：

<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy">
  <RefreshToken ref="request.queryparam.refresh_token"/>
</GetOAuthV2Info>

有了重新整理權杖，政策會查詢重新整理權杖的資訊，並填入一組含有重新整理權杖資料的變數。

然後，您可以使用 JavaScript 或其他方式存取這些變數。以下範例使用 JavaScript 擷取與重新整理權杖相關聯的自訂屬性：

var attr = context.getVariable('oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name');

請注意，如要在程式碼中存取變數，必須加上「oauthv2refreshtoken」前置字元。如需透過重新整理權杖取得的變數完整清單，請參閱「重新整理權杖變數」。

靜態

在極少數情況下，您可能需要取得靜態設定的權杖 (無法透過變數存取的權杖) 的設定檔。方法是將存取權杖的值做為元素提供。

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
</GetOAuthV2Info>

您也可以對所有其他權杖類型 (用戶端 ID、授權碼和重新整理權杖) 執行這項操作。

用戶端 ID

這個範例說明如何使用用戶端 ID 擷取用戶端應用程式的相關資訊。執行時，政策會填入一組含有用戶端資訊的變數。在本例中，政策預期會在名為 client_id 的查詢參數中找到用戶端 ID。政策會根據用戶端 ID 查詢用戶端設定檔，並填入一組含有設定檔資料的變數。變數會加上 oauthv2client. 前置字串

<GetOAuthV2Info name="GetClientAttributes">
  <ClientId ref="request.queryparam.client_id"></ClientId>
</GetOAuthV2Info>

然後，您可以使用 JavaScript 或其他方式存取變數。舉例來說，如要使用 JavaScript 取得與用戶端應用程式相關聯的開發人員應用程式名稱和開發人員電子郵件地址，請執行下列操作：

context.getVariable("oauthv2client.GetClientAttributes.developer.email");
context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");

元素參照

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1"
    <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref="variable"></AccessToken>
    <AuthorizationCode ref="variable"></AuthorizationCode>
    <ClientId ref="variable"></ClientId>
    <RefreshToken ref="variable"></RefreshToken>
</GetOAuthV2Info>

<GetOAuthV2Info> 屬性

<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">

下表說明所有政策父項元素的共同屬性：

屬性	說明	預設	存在必要性
`name`	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
`continueOnError`	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
`enabled`	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設

預設	不適用如果省略這個元素，系統會使用政策的 `name` 屬性值。
存在必要性	選用
類型	字串

不適用

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

存在必要性選用

類型字串

<AccessToken> 元素

擷取存取權杖的設定檔。您可以傳入包含存取權杖字串的變數，或權杖字串常值 (少見)。在本範例中，存取權杖是從要求中傳遞的查詢參數擷取。如要傳回遭撤銷或過期權杖的資訊，請使用 <IgnoreAccessTokenStatus> 元素。

<AccessToken ref="request.queryparam.access_token"></AccessToken>

預設值：	request.formparam.access_token (x-www-form-urlencoded，且在要求主體中指定)
外觀狀態：	選用
類型：	字串
有效值：	包含存取權權杖字串的流程變數，或字串常值。

<AuthorizationCode> 元素

擷取授權碼的設定檔。您可以傳入包含授權碼字串的變數，或是傳入字面值權杖字串 (少見情況)。在本範例中，驗證碼是從要求中傳遞的查詢參數擷取而來。如需這項作業填入的變數清單，請參閱「流程變數」。

<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>

預設值：	request.formparam.access_token (x-www-form-urlencoded，且在要求主體中指定)
外觀狀態：	選用
類型：	字串
有效值：	包含授權碼字串的流程變數，或字串文字。

<ClientId> 元素

擷取與用戶端 ID 相關的資訊。在本範例中，系統會從要求中傳遞的查詢參數擷取用戶端 ID。如需這項作業填入的變數清單，請參閱「流程變數」。

<ClientId ref="request.queryparam.client_id"></ClientId>

預設值：	request.formparam.access_token (x-www-form-urlencoded，且在要求主體中指定)
外觀狀態：	選用
類型：	字串
有效值：	包含授權碼字串的流程變數，或字串文字。

<IgnoreAccessTokenStatus> 元素

即使權杖過期或遭撤銷，仍會傳回權杖資訊。這個元素只能搭配存取權杖使用。根據預設，系統會傳回其他實體的資訊，例如重新整理權杖和授權碼，無論這些實體的狀態為何。

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

預設值：	false
外觀狀態：	選用
類型：	布林值
有效值：	true 或 false

<RefreshToken> 元素

擷取更新權杖的設定檔。您可以傳入包含重新整理權杖字串的變數，或傳入權杖字串文字 (少見情況)。在本例中，重新整理權杖是從要求中傳遞的查詢參數擷取。如需這項作業填入的變數清單，請參閱「流程變數」。

<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>

預設值：	request.formparam.access_token (x-www-form-urlencoded，且在要求主體中指定)
外觀狀態：	選用
類型：	字串
有效值：	包含重新整理權杖字串的流程變數，或字串常值。

流程變數

GetOAuthV2Info 政策會填入這些變數，通常用於需要設定檔資料，但尚未授予或驗證的情況。。

用戶端 ID 變數

設定 ClientId 元素時，系統會填入這些變數：

oauthv2client.{policy_name}.client_id
oauthv2client.{policy_name}.client_secret
oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'
oauthv2client.{policy_name}.developer.email
oauthv2client.{policy_name}.developer.app.name
oauthv2client.{policy_name}.developer.id
oauthv2client.{policy_name}.{developer_app_custom_attribute_name}

存取權杖變數

設定 AccessToken 元素時，系統會填入下列變數：

oauthv2accesstoken.{policy_name}.developer.id
oauthv2accesstoken.{policy_name}.developer.app.name
oauthv2accesstoken.{policy_name}.developer.app.id
oauthv2accesstoken.{policy_name}.developer.email

oauthv2accesstoken.{policy_name}.organization_name
oauthv2accesstoken.{policy_name}.api_product_list

oauthv2accesstoken.{policy_name}.access_token
oauthv2accesstoken.{policy_name}.scope
oauthv2accesstoken.{policy_name}.expires_in //in seconds
oauthv2accesstoken.{policy_name}.status
oauthv2accesstoken.{policy_name}.client_id
oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2accesstoken.{policy_name}.refresh_token
oauthv2accesstoken.{policy_name}.refresh_token_status
oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2accesstoken.{policy_name}.refresh_count
oauthv2accesstoken.{policy_name}.refresh_token_issued_at
oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

授權碼變數

設定 AuthorizationCode 元素時，系統會填入下列變數：

oauthv2authcode.{policy_name}.code
oauthv2authcode.{policy_name}.scope       
oauthv2authcode.{policy_name}.redirect_uri 
oauthv2authcode.{policy_name}.client_id
oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

更新權杖變數

設定 RefreshToken 元素時，系統會填入下列變數：

oauthv2refreshtoken.{policy_name}.developer.id
oauthv2refreshtoken.{policy_name}.developer.app.name
oauthv2refreshtoken.{policy_name}.developer.app.id
oauthv2refreshtoken.{policy_name}.developer.email
oauthv2refreshtoken.{policy_name}.organization_name
oauthv2refreshtoken.{policy_name}.api_product_list

oauthv2refreshtoken.{policy_name}.access_token
oauthv2refreshtoken.{policy_name}.scope
oauthv2refreshtoken.{policy_name}.expires_in //in seconds

oauthv2refreshtoken.{policy_name}.status
oauthv2refreshtoken.{policy_name}.client_id
oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2refreshtoken.{policy_name}.refresh_token
oauthv2refreshtoken.{policy_name}.refresh_token_status
oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2refreshtoken.{policy_name}.refresh_count
oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

結構定義

每個政策類型都由 XML 架構 (.xsd) 定義。如需參考，請前往 GitHub 查看政策架構。

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。下方顯示的錯誤名稱是發生錯誤時，指派給 fault.name 變數的字串。詳情請參閱下方的「錯誤變數」一節。

錯誤代碼	HTTP 狀態	原因
`steps.oauth.v2.access_token_expired`	`500`	傳送至政策的存取權權杖已過期。
`steps.oauth.v2.authorization_code_expired`	`500`	傳送至政策的授權碼已過期。
`steps.oauth.v2.invalid_access_token`	`500`	傳送至政策的存取權杖無效。
`steps.oauth.v2.invalid_client-invalid_client_id`	`500`	傳送至政策的客戶端 ID 無效。
`steps.oauth.v2.invalid_refresh_token`	`500`	傳送至政策的更新權杖無效。
`steps.oauth.v2.invalid_request-authorization_code_invalid`	`500`	傳送至政策的授權碼無效。
`steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound`	401	如要瞭解如何排解此錯誤，請參閱「 Oauth2.0 存取權杖驗證會擲回「找不到相符的 apiproduct，因此 API 呼叫無效」錯誤」一文。
`steps.oauth.v2.refresh_token_expired`	`500`	傳送至政策的更新權杖已過期。

部署錯誤

請參閱 UI 中回報的訊息，瞭解部署錯誤。

錯誤變數

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

變數	地點	範例
`fault.name="fault_name"`	`fault_name` 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。	`fault.name Matches "IPDeniedAccess"`
`oauthV2.policy_name.failed`	`policy_name` 是擲回錯誤的政策的使用者指定名稱。	`oauthV2.GetTokenInfo.failed = true`
`oauthV2.policy_name.fault.name`	`policy_name` 是擲回錯誤的政策的使用者指定名稱。	`oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id`
`oauthV2.policy_name.fault.cause`	`policy_name` 是擲回錯誤的政策的使用者指定名稱。	`oauthV2.GetTokenInfo.cause = ClientID is Invalid`

錯誤回應範例

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

錯誤規則範例

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>