要求 API 金鑰來保護 API

請務必保護 API，防止他人在未經授權的情況下擅自存取。其中一種做法是使用 API 金鑰。

如果應用程式向設定為驗證 API 金鑰的 API Proxy 提出要求，就必須提供有效的金鑰。在執行階段，Verify API Key 政策會檢查提供的 API 金鑰是否符合下列條件：

有效
未遭撤銷
與公開所要求資源的 API 產品 API 金鑰相符

如果金鑰有效，系統就會允許要求。如果金鑰無效，要求會導致授權失敗。

建立 API Proxy

前往 Apigee UI 並登入帳戶。
使用使用者介面左上角的下拉式選單選取機構。
依序點選「Develop」>「API Proxies」，顯示 API Proxy 清單。
按一下「建立新項目」。
在「Build a Proxy」精靈中，選取「Reverse proxy (most common)」(反向 Proxy (最常見))。

設定 Proxy 的步驟如下：

在這個欄位中	請按照下列步驟操作
Proxy 名稱	輸入：`helloworld_apikey`
專案基本路徑	變更為：`/helloapikey` 專案基準路徑是網址的一部分，用於向 API 代理發出要求。
說明	輸入：`hello world protected by API key`
目標 (現有 API)	輸入：`http://mocktarget.apigee.net` 這會定義 Apigee 在對 API Proxy 發出要求時叫用的目標網址。這個目標只會回傳簡單的回應：`Hello, Guest!`。

點選「下一步」。
在「通用政策」頁面上，選取「API 金鑰」。這個選項會自動在 API 代理中新增兩項政策，並建立產生 API 金鑰所需的 API 產品。
點選「下一步」。
在「摘要」頁面中，確認已選取部署環境，然後按一下「建立並部署」。
按一下「編輯 Proxy」，即可顯示 API Proxy 的「總覽」頁面。

查看政策

在 API Proxy 編輯器中，按一下「開發」分頁標籤。您會看到 API 代理的要求流程中新增了兩項政策：
- 驗證 API 金鑰：檢查 API 呼叫，確保其中含有有效的 API 金鑰 (以查詢參數形式傳送)。
- 移除查詢參數 apikey：指派訊息政策會在檢查 API 金鑰後移除該金鑰，避免金鑰在不必要的情況下傳遞及公開。
在流程檢視畫面中，按一下「Verify API Key」政策圖示，然後查看下方程式碼檢視畫面中的政策 XML 設定。<APIKey> 元素會告知政策，在進行呼叫時應從何處尋找 API 金鑰。根據預設，系統會在 HTTP 要求中，尋找名為 apikey 的查詢參數做為金鑰：
```
<APIKey ref="request.queryparam.apikey" />
```
名稱 apikey 是任意名稱，可以是包含 API 金鑰的任何屬性。

嘗試呼叫 API

在這個步驟中，您會直接向目標服務發出成功的 API 呼叫，然後向 API 代理發出失敗的呼叫，瞭解政策如何保護 API 代理。

成功

在網路瀏覽器中前往下列網址，這是 API Proxy 設定要將要求轉送至的目標服務，但您目前會直接存取該服務：
```
http://mocktarget.apigee.net
```
您應該會收到以下成功回應：Hello, Guest!
失敗

現在請嘗試呼叫 API Proxy：
```
curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey
```
其中 YOUR ENV_GROUP_HOSTNAME 是環境群組主機名稱。請參閱「找出環境群組主機名稱」。

注意： 如果無法呼叫 Proxy，您可能需要新增 Host 標頭，詳情請參閱「部署 Proxy 範例」。

如果沒有「驗證 API 金鑰」政策，這次呼叫會傳回與上次呼叫相同的回應。但在此情況下，您應該會收到下列錯誤回應：
```
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
```
這表示您未傳遞有效的 API 金鑰 (做為查詢參數)。

在後續步驟中，您將取得必要的 API 金鑰。

新增 API 產品

如要使用 Apigee UI 新增 API 產品，請按照下列步驟操作：

依序選取「發布」>「API 產品」。
點選「+建立」。

輸入 API 產品的產品詳細資料。

欄位	說明
名稱	API 產品的內部名稱。名稱中不得包含特殊字元。注意：API 產品建立完成後，您就無法編輯名稱。
顯示名稱	API 產品的顯示名稱。顯示名稱會顯示在使用者介面中，且隨時可以編輯。如未指定，系統會使用「名稱」值。系統會使用「名稱」值自動填入這個欄位，您可以編輯或刪除其內容。顯示名稱可以包含特殊字元。
說明	API 產品的說明。
環境	API 產品允許存取的環境。例如 `test` 或 `prod`。
存取	選取 Public。
自動核准存取要求	針對任何應用程式，啟用這項 API 產品的金鑰要求自動核准功能。
配額	在本教學課程中，請忽略這項錯誤。
允許的 OAuth 範圍	在本教學課程中，請忽略這項錯誤。

在「Operations」部分中，按一下「ADD AN OPERATION」。
在「API Proxy」欄位中，選取您剛建立的 API Proxy。
在「路徑」欄位中輸入「/」，並忽略其他欄位。
按一下「儲存」儲存作業。
按一下「儲存」儲存 API 產品。

在機構中新增開發人員和應用程式

接下來，我們要模擬開發人員註冊使用您 API 的工作流程。開發人員會有一或多個呼叫您 API 的應用程式，每個應用程式都會取得專屬 API 金鑰。API 供應商可藉此更精細地控管 API 存取權，並取得更精細的應用程式 API 流量報表。

建立開發人員

如要建立開發人員：

在選單中依序選取「發布」>「開發人員」。
注意：如果仍停留在「開發」畫面，請按一下「DEVELOP」旁的「<」，顯示選單並選取「發布」>「開發人員」。
按一下「+ 開發人員」。

在「New Developer」(新開發人員) 視窗中輸入下列資訊：

在這個欄位中	Enter 鍵
名字	`Keyser`
姓氏	`Soze`
使用者名稱	`keyser`
電子郵件	`keyser@example.com`

點選「建立」。

註冊應用程式

如要註冊開發人員應用程式，請按照下列步驟操作：

依序選取「發布」>「應用程式」。
按一下「+ 應用程式」。

在「New Developer App」(新增開發人員應用程式) 視窗中輸入下列內容：

在這個欄位中	請按照下列步驟操作：
名稱和顯示名稱	輸入：`keyser_app`
開發人員	選取：`Keyser Soze (keyser@example.com)`
回呼網址和附註	留空

在「憑證」部分中，選取「永不」。這個應用程式的憑證永不過期。
按一下「新增產品」。
選取剛建立好的產品。
點選「建立」。

取得 API 金鑰

如要取得 API 金鑰，請按照下列步驟操作：

在「應用程式」頁面 (依序點選「發布」>「應用程式」)，按一下「keyser_app」keyser_app。
在「keyser_app」keyser_app頁面中，按一下「憑證」部分中「金鑰」旁的「顯示」。請注意，金鑰會與您建立的產品建立關聯。
選取並複製金鑰。您會在下一個步驟中使用此項目。

使用金鑰呼叫 API

現在您已取得 API 金鑰，可以呼叫 API Proxy。如畫面所示，將 API 金鑰貼到查詢參數中。確認查詢參數中沒有多餘的空格。

curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=your_api_key

現在呼叫 API Proxy 時，您應該會收到以下回應：Hello, Guest!

恭喜！您已建立 API Proxy，並要求在呼叫中加入有效的 API 金鑰，藉此保護 API Proxy。

請注意，一般而言，不建議將 API 金鑰做為查詢參數傳遞。建議您改為在 HTTP 標頭中傳遞。

最佳做法：在 HTTP 標頭中傳遞金鑰

在這個步驟中，您將修改 Proxy，在名為 x-apikey 的標頭中尋找 API 金鑰。

編輯 API Proxy。依序選取「Develop」>「API Proxies」>「helloworld_apikey」，然後前往「Develop」檢視畫面。
選取「Verify API Key」政策，並修改政策 XML，告知政策在 header 中尋找，而非在 queryparam 中尋找：
```
<APIKey ref="request.header.x-apikey"/>
```
儲存 API Proxy，然後使用「部署」部署。
使用 cURL 進行下列 API 呼叫，將 API 金鑰做為名為 x-apikey 的標頭傳遞。別忘了代入貴機構名稱。
```
curl -v -H "x-apikey: {api_key_goes_here}" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey
```

請注意，如要完全完成變更，您也需要設定「指派訊息」政策，移除標頭而非查詢參數。例如：

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>