要求 API 金鑰來保護 API

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

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

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

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

建立 API Proxy

請按照下列步驟，使用 Apigee UI 建立 API Proxy：

在 Google Cloud 控制台中，前往「Apigee」>「Proxy 開發」>「API Proxy」頁面。

前往 API Proxy
在 Google Cloud 窗格的專案挑選器中選取機構。組織名稱與 Google Cloud 專案名稱相同。
點選「+ 建立」。
在「建立 Proxy」窗格的「Proxy template」下方，選取「Reverse proxy (Most common)」。反向 Proxy 會將傳入流量轉送至後端服務。

請按照下列步驟設定 Proxy：

名稱	值
Proxy 名稱	`helloworld_apikey`
基本路徑	`/helloapikey` 專案基本路徑是網址的一部分，用於向 API Proxy 發出要求。
說明	`hello world protected by API key`
目標 (現有 API)	`http://mocktarget.apigee.net` 這會定義 Apigee 在對 API Proxy 發出要求時叫用的目標網址。這個目標只會回傳簡單的回應：`Hello, Guest!`。

點選「下一步」。
部署 (選用)。將這些欄位留空。
點選「建立」。
Apigee 會建立新的 Proxy，並在「Proxy summary」窗格中顯示 Proxy 詳細資料摘要。

查看政策

如要查看政策，請按照下列步驟操作：

在「helloworld_apikey」Proxy 的「Proxy summary」窗格中，點選「Develop」分頁標籤。
在「政策」選單中，按一下「新增政策」。
在「建立政策」窗格中，選取「安全性」下方的「驗證 API 金鑰」。
在「Verify API Key」窗格中，使用下列值填寫「Name」和「Display name」部分中的必填欄位：
- 名稱：輸入政策名稱。例如：VerifyAPIKey。
- 顯示名稱：輸入要在使用者介面中使用的政策名稱。例如：Verify API Key。
點選「建立」。
按一下即可新增其他政策。
在「建立政策」窗格的「中介服務」下方，選取「指派訊息」。
在「Assign Message」窗格中，使用下列值填妥「Name」和「Display name」部分中的必填欄位：
- 名稱：輸入政策名稱。例如：AssignMessage。
- 顯示名稱：輸入要在使用者介面中使用的政策名稱。例如：Assign Message。
點選「建立」。
下方的 XML 程式碼中的 <APIKey> 元素，會指定傳入要求中 API 金鑰的位置。根據預設，這項政策會從 HTTP 要求中名為 apikey 的查詢參數擷取金鑰。
```
<APIKey ref="request.queryparam.apikey" />
```
名稱 apikey 是任意名稱，可以是包含 API 金鑰的任何屬性。
將「Assign Message」政策的內容更新為下列內容：
注意：進行這項編輯後，政策名稱會變更為 Remove Query Param apikey。

<AssignMessage async="false" continueOnError="false" enabled="true" name="remove-query-param-apikey">
    <DisplayName>Remove Query Param apikey</DisplayName>
    <Remove>
        <QueryParams>
            <QueryParam name="apikey"/>
        </QueryParams>
    </Remove>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

新增 VerifyApiKey 和 Remove Query Param apikey 政策。
1. 在「Proxy endpoints」選單中，點選「Preflow」。
2. 在視覺編輯器的「要求」窗格中，按一下「新增政策步驟」。
3. 在「新增政策步驟」窗格中，選取「驗證 API 金鑰」。
4. 按一下「新增」。
5. 在視覺編輯器的「要求」窗格中，按一下「新增政策步驟」。
6. 在「新增政策步驟」窗格中，選取「Remove Query Param apikey」。
7. 按一下「新增」。
按一下 [儲存]。
將 Proxy 部署至環境：
1. 點選「Deploy」(部署)。
2. 選取「修訂版本」和「環境」。
3. 點選「Deploy」(部署)。
如要測試變更，請按照「嘗試呼叫 API」一節的說明呼叫 API。

嘗試呼叫 API

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

成功

使用網路瀏覽器前往下列網址。這是 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 產品，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「發布」>「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 供應商可以藉此更精細地控管 API 存取權，並取得更精細的應用程式 API 流量報表。

建立開發人員

如要使用 Apigee UI 建立開發人員，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「發布」>「開發人員」頁面：

前往「開發人員」
點選「+ 建立」。

在「新增開發人員」視窗中輸入下列資訊：

欄位	值
名字	`Keyser`
姓氏	`Soze`
電子郵件	`keyser@example.com`
使用者名稱	`keyser`

按一下「新增」。

如要進一步瞭解如何建立開發人員，請參閱「註冊應用程式開發人員」。

註冊應用程式

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

在 Google Cloud 控制台中，前往 「Distribution」 >「Apps」頁面：
前往「應用程式」
點選「+ 建立」。

在「建立應用程式」視窗中輸入下列資訊：

欄位	值
應用程式名稱	輸入：`keyser_app`
顯示名稱	輸入：`keyser_app`
開發人員	選取：`Keyser Soze (keyser@example.com)`
回呼網址	留空
注意事項	留空

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

如要進一步瞭解如何註冊應用程式，請參閱「註冊應用程式」。

取得 API 金鑰

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

在 Google Cloud 控制台中，依序前往「Apigee」>「Distribution」 >「Apps」頁面。

前往「應用程式」
從應用程式清單中選取所需應用程式。
在「View app」(查看應用程式) 頁面，點選「Credentials」(憑證) 下方的「Key」(金鑰) 欄位旁的。請注意，金鑰會與您建立的產品建立關聯。
按一下「複製」。您會在下一個步驟中使用這組金鑰。

使用金鑰呼叫 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 金鑰，藉此保護 Proxy。

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

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

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

在 Google Cloud 控制台中，前往 「Proxy 開發」 > 「API Proxy」頁面。

前往 API Proxy

從 Proxy 清單中選取所需 Proxy。
在「Proxy details」(Proxy 詳細資料) 頁面上，按一下「Develop」(開發)。
修改政策 XML，告知政策在標頭中尋找，而非在查詢參數中尋找：

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

按一下「儲存」儲存變更。
點選「Deploy」(部署)。
選取「修訂版本」和「環境」。
點選「Deploy」(部署)。
使用 cURL 發出下列 API 呼叫，將 API 金鑰做為名為 x-apikey 的標頭傳遞。別忘了代入貴機構的名稱。
```
curl -v -H "x-apikey: YOUR_API_KEY" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey
```

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

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