驗證 APIKey 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

結果

「驗證 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 UI 中查看或存取應用程式的用戶端金鑰和密鑰組

在應用程式註冊時，開發人員會選取一或多項 API 產品來 與應用程式建立關聯，其中 API 產品是一組 資源 可透過 API Proxy 存取接著，開發人員會將 API 金鑰 (用戶端金鑰) 做為 應用程式相關 API 產品中 API 的每個要求。詳情請參閱「發布總覽」。

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

執行 Verify 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">

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

<DisplayName>元素

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

<DisplayName>Policy Display Name</DisplayName>

<APIKey>元素

此元素會指定包含 API 金鑰的流程變數。一般來說，用戶端會傳送 API 金鑰 查詢參數、HTTP 標頭或表單參數中舉例來說，如果金鑰是在標頭中傳送 名為 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>

結構定義

流程變數

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

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

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

每種流程變數都有不同的前置字元。所有變數均為純量，除了這些項目 並明確表示為陣列

一般流程變數

下表列出「Verify 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 金鑰政策時，Analytics 會自動填入下列變數 強制針對有效 API 金鑰強制執行這些變數只會由 Verify API 金鑰填入 政策和 OAuth 政策

您可以使用變數和值建立 Analytics 報表，進而取得 瞭解開發人員和應用程式的消費模式

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

錯誤參考資料

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 Edge 所設定的錯誤變數。 請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則， 處理錯誤詳情請參閱這篇文章 瞭解政策錯誤和處理方式 發生錯誤

執行階段錯誤

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

部署錯誤

當您部署含有這項政策的 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>

相關主題