驗證 APIKey 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

總覽

您可以透過「驗證 API 金鑰」政策，在執行階段強制執行 API 金鑰驗證，讓只有擁有核准 API 金鑰的應用程式才能存取您的 API。這項政策可確保 API 金鑰有效且未遭到撤銷，並且已獲准使用與 API 產品相關聯的特定資源。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

如需教學課程，瞭解如何建構使用「驗證 API 金鑰」政策的 API Proxy，請參閱「透過要求 API 金鑰保護 API」一文。

範例

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
    <Source>request</Source>
    <QueryParam name="myKey">
        <Pattern ignoreCase="true">{key}</Pattern>
    </QueryParam>
    <VariablePrefix>requestAPIKey</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
    <AssignVariable>
        <Name>devFirstName</Name>
        <Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devLastName</Name>
        <Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devEmail</Name>
        <Ref>verifyapikey.verify-api-key.developer.email</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

verifyapikey.{policy_name}

關於「驗證 API 金鑰」政策

開發人員在 Apigee 上註冊應用程式時，Apigee 會自動產生消費者金鑰和密碼組。您可以在 Apigee UI 中查看應用程式的消費者金鑰和密鑰組合，或透過 Apigee API 存取這些項目。

在應用程式註冊時，開發人員會選取一或多個 API 產品 與應用程式建立關聯，其中 API 產品是透過 API 代理程式存取的資源集合。接著，開發人員會將 API 金鑰 (消費者金鑰) 傳遞至與應用程式相關聯的 API 產品中，做為對 API 的每個要求的一部分。詳情請參閱發布概覽。

API 金鑰可用於驗證權杖，也可以用來取得 OAuth 存取權杖。在 OAuth 中，API 金鑰會稱為「用戶端 ID」。這兩個名稱可以交替使用。詳情請參閱 OAuth 首頁。

執行「驗證 API 金鑰」政策時，Apigee 會自動填入一組流程變數。詳情請參閱下方的「動態變數」。

元素參考

以下是您可以在這項政策中設定的元素和屬性：

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <APIKey ref="variable_containing_api_key"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</VerifyAPIKey>

<VerifyAPIKey> 屬性

以下範例顯示 <VerifyAPIKey> 標記上的屬性：

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

<APIKey> 元素

這個元素會指定包含 API 金鑰的資料流變數。通常，用戶端會在查詢參數、HTTP 標頭或表單參數中傳送 API 金鑰。舉例來說，如果金鑰是在名為 x-apikey 的標頭中傳送，您可以在變數中找到該金鑰：request.header.x-apikey

屬性

下表說明 <APIKey> 元素的屬性

範例

在這些範例中，系統會在參數和名為 x-apikey 的標頭中傳遞金鑰。

做為查詢參數：

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>

做為 HTTP 標頭：

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

做為 HTTP 表單參數：

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

<CacheExpiryInSeconds> 元素

這個元素會在快取中強制執行 TTL，讓您自訂快取存取權權杖到期時間。支援的範圍介於 1 到 180 秒之間。您可以提供流程變數和預設變數。如果提供，流程變數值會優先於指定的預設值。

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>

屬性

下表說明 <CacheExpiryInSeconds> 元素的屬性

結構定義

流程變數

當您對有效的 API 金鑰強制執行「驗證 API 金鑰」政策時，Apigee 會填入一組流程變數。這些變數可供稍後在流程中執行的政策或程式碼使用，通常用於根據 API 金鑰的屬性執行自訂處理作業，例如應用程式名稱、用於授權金鑰的 API 產品，或 API 金鑰的自訂屬性。

這項政策會填入多種不同類型的流程變數，包括：

• 一般
• 應用程式
• 開發人員
• Analytics
• 營利

每種流程變數類型都有不同的前置字串。除了特別標示為陣列的變數，所有變數都是標量。

一般流程變數

下表列出「驗證 API 金鑰」政策填入的一般流程變數。這些變數的開頭都會加上：

verifyapikey.{policy_name}

例如：verifyapikey.{policy_name}.client_id

可用的變數包括：

應用程式流程變數

政策會填入下列包含應用程式相關資訊的流程變數。這些變數的開頭都會加上：

verifyapikey.{policy_name}.app。

例如：

verifyapikey.{policy_name}.app.name

可用的變數包括：

AppGroup 流程變數

政策會填入下列包含 AppGroups 相關資訊的流程變數。只有在 verifyapikey.{policy_name}.app.appType 為「AppGroup」時，這些 AppGroup 屬性才會填入。

這些變數的開頭都會加上：

verifyapikey.{policy_name}.appgroup。

例如：

verifyapikey.{policy_name}.appgroup.name

可用的變數包括：

開發人員流程變數

政策會填入下列包含開發人員相關資訊的流程變數。這些變數的開頭都會加上：

verifyapikey.{policy_name}.developer

例如：

verifyapikey.{policy_name}.developer.id

可用的變數包括：

Analytics 變數

針對有效的 API 金鑰強制執行「驗證 API 金鑰」政策時，Analytics 會自動填入下列變數。只有「驗證 API 金鑰」政策和 OAuth 政策會填入這些變數。

這些變數和值可做為維度，用於建立 Analytics 報表，以便瞭解開發人員和應用程式使用的模式。

• apiproduct.name
• developer.app.name
• client_id
• developer.id

營利流程變數

驗證使用者後，VerifyAPIKey 政策會檢查所有已發布的費率方案，根據啟用和到期時間判斷哪些方案處於有效狀態。如果找到有效的已發布房價方案，系統會填入下列流程變數：

錯誤參考資料

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

執行階段錯誤

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

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤變數

這些變數會在發生執行階段錯誤時設定。詳情請參閱「關於政策錯誤的相關資訊」。

錯誤回應範例

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}

{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

錯誤規則範例

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>