要求 API 金鑰來保護 API

請務必保護 API，防止他人在未經授權的情況下擅自存取。其中一種方式是使用 API 金鑰 (也稱為公開金鑰、消費者金鑰或應用程式金鑰)。

應用程式向您的 API 發出要求時，必須提供有效金鑰。在執行階段，Verify API Key 政策會檢查提供的 API 金鑰是否符合下列條件：

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

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

在本教學課程中，您將建立 API Proxy，要求使用者必須提供有效的 API 金鑰才能存取。

軟硬體需求

Apigee Edge 帳戶。如果還沒有帳戶，請按照「建立 Apigee Edge 帳戶」一文中的指示註冊。
用於發出 API 呼叫的網頁瀏覽器。
(額外學分部分，非必要條件) 您的電腦上已安裝 cURL，可從指令列發出 API 呼叫。

建立 API Proxy

前往 https://apigee.com/edge 並登入。
按一下側邊導覽列頂端的使用者名稱，顯示使用者設定檔選單，然後從清單中選取所需機構，即可切換機構。
在到達網頁上按一下「API Proxy」，即可顯示 API Proxy 清單。
按一下「+ Proxy」。
在「建立 Proxy」頁面中，選取「反向 Proxy (最常見)」。

在「Proxy Details」頁面中，按照下列方式設定 Proxy：

在這個欄位中	請按照下列步驟操作：
Proxy 名稱	輸入：`helloworld_apikey`
專案基本路徑	變更為：`/helloapikey` 專案基本路徑是網址的一部分，用於向 API Proxy 提出要求。附註：如要瞭解 Apigee 的 API 版本管理建議，請參閱「Web API Design: The Missing Link」電子書中的「版本管理」一節。
現有 API	輸入：`http://mocktarget.apigee.net` 這會定義 Apigee Edge 在對 API Proxy 發出要求時，所叫用的目標網址。
說明	輸入：`hello world protected by API key`

點選 [下一步]。
在「Common Policies」(通用政策) 頁面中，針對「Security: Authorization」(安全性：授權)，選取「API Key」(API 金鑰)，然後按一下「Next」(下一步)。這會將兩項政策新增至 API Proxy。
在「Virtual Hosts」頁面中，選取「default」和「secure」，然後按一下「Next」。選取「預設」即可使用 http:// 呼叫 API。選取「安全」，即可使用 https:// 呼叫 API。
在「摘要」頁面，確認已選取「測試」部署環境，然後按一下「建立並部署」。
您會看到確認訊息，指出系統已成功建立新的 API Proxy 和 API 產品，並將 API Proxy 部署至測試環境。
按一下「編輯 Proxy」，顯示 API Proxy 的「總覽」頁面。

查看政策

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

嘗試呼叫 API

在本步驟中，您將直接向目標服務發出成功的 API 呼叫，然後向 API Proxy 發出不成功的呼叫，瞭解政策如何保護 API Proxy。

成功

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

現在嘗試呼叫 API Proxy：
```
http://ORG_NAME-test.apigee.net/helloapikey
```
將 ORG_NAME 改成 Edge 機構的名稱。

如果沒有「驗證 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 產品建立完成後，您就無法編輯名稱。例如：`helloworld_apikey-Product`。
顯示名稱	API 產品的顯示名稱，顯示名稱會顯示在使用者介面中，而且隨時可以編輯。如未指定，系統會使用「名稱」值。系統會使用「名稱」值自動填入這個欄位，您可以編輯或刪除其中的內容。顯示名稱可以包含特殊字元。例如： `helloworld_apikey-Product`。
說明	API 產品的說明。例如 `Test product for tutorial`。
環境	API 產品允許存取的環境。例如 `test` 或 `prod`
存取權	選取「公開」。
自動核准存取要求	針對任何應用程式，自動核准這個 API 產品的金鑰要求。
配額	在本教學課程中，請忽略這項錯誤。
允許的 OAuth 範圍	在本教學課程中，請忽略這項錯誤。

在 API 資源部分，選取您剛建立的 API Proxy。例如 helloworld_apikey。
按一下 [新增]。
在「Paths」(路徑) 區段中，新增路徑「/」。
按一下 [新增]。
按一下 [儲存]。

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

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

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

建立開發人員

如要建立開發人員：

在選單中依序選取「發布」>「開發人員」。
按一下「+ 開發人員」。

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

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

點選「建立」。

註冊應用程式

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

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

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

p

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

在「憑證」部分，從「有效期限」選單中選取「永不」。這個應用程式的憑證永不過期。
在「產品」下方，按一下「新增產品」。
選取「helloworld_apikey-Product」。
按一下 [新增]。
按一下「應用程式詳細資料」部分上方和右側的「建立」，儲存您的工作。

取得 API 金鑰

取得 API 金鑰的方法如下：

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

使用金鑰呼叫 API

現在您已取得 API 金鑰，可以呼叫 API Proxy。在網路瀏覽器中輸入下列網址。將下列 ORG_NAME 替換為 Edge 機構名稱，並將 API_KEY 替換為 API 金鑰。確認查詢參數中沒有多餘空格。

http://ORG_NAME-test.apigee.net/helloapikey?apikey=API_KEY

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

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

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

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

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

編輯 API Proxy。依序選取「開發」>「API Proxy」>「helloworld_apikey」，然後前往「開發」檢視畫面。
選取「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" http://ORG_NAME-test.apigee.net/helloapikey
```

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

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