驗證 APIKey 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

您可以使用「驗證 API 金鑰」政策，在執行階段強制驗證 API 金鑰，只允許具有核准 API 金鑰的應用程式存取 API。這項政策可確保 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 金鑰」政策

開發人員在 Edge 註冊應用程式時，Edge 會自動產生一組消費者金鑰和密碼。您可以在 Edge 使用者介面中查看應用程式的消費者金鑰和密鑰配對，也可以透過 Edge API 存取這些資訊。

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

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

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

元素參照

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

<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"/>
</VerifyAPIKey>

<VerifyAPIKey> 屬性

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

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

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

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<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>

結構定義

流程變數

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

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

• 一般
• 應用程式
• 開發人員
• 公司
• Analytics

每種流程變數都有不同的前置字元。除非特別指出為陣列，否則所有變數都是純量。

一般流程變數

下表列出「驗證 API 金鑰」政策填入的一般流程變數。這些變數的前置字元都是：

verifyapikey.{policy_name}

例如：verifyapikey.{policy_name}.client_id

可用的變數包括：

應用程式流程變數

政策會填入下列含有應用程式相關資訊的流程變數： 這些變數的前置字元都是：

verifyapikey.{policy_name}.app。

例如：

verifyapikey.{policy_name}.app.name

可用的變數包括：

開發人員流程變數

下列含有開發人員資訊的流程變數會由政策填入。這些變數的前置字元都是：

verifyapikey.{policy_name}.developer

例如：

verifyapikey.{policy_name}.developer.id

可用的變數包括：

公司流程變數

下列包含公司資訊的流程變數是由政策填入。這些變數的前置字元都是：

verifyapikey.{policy_name}.company

例如：

verifyapikey.{policy_name}.company.name

可用的變數包括：

Analytics 變數

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

變數和值可用做維度，建立 Analytics 報表，瞭解開發人員和應用程式的用量模式。

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

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error responses

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

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

Example fault rule

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

相關主題