作業指南

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

如何取得 API 金鑰

以下範例說明如何取得 API 金鑰，以便驗證透過 Apigee Adapter for Envoy 代理的目標服務 API 呼叫。

1. 登入 Apigee

1. 在瀏覽器中開啟 Apigee UI。
2. 進入使用者介面後，請選取您用於為 Envoy 設定 Apigee Adapter 的機構。

2. 可建立開發人員

您可以使用現有的開發人員進行測試，也可以按照下列步驟建立新的開發人員：

1. 在側邊導覽選單中，依序選取「發布」>「開發人員」。
2. 按一下「+ 開發人員」。
3. 填寫對話方塊，建立新的開發人員。您可以使用任何開發人員名稱/電子郵件地址。

3. 可建立 API 產品

請參考下方提供的產品建立範例。另請參閱「關於 API 產品設定」。

1. 在側邊導覽選單中，依序選取「發布」>「API 產品」。
2. 按一下「+ API 產品」。
3. 請按照下列指示填寫「產品詳細資料」頁面。請勿點選「儲存」，直到系統提示為止。

欄位	值
名稱	httpbin-product
顯示名稱	httpbin product
環境	your_environment 請將此值設為您使用 apigee-remote-service-cli 為 Envoy 佈建 Apigee Adapter 時所用的環境。
存取權	Private
配額	每 1 分鐘 5 次要求 另請參閱「關於 API 產品」。

4. 在「Apigee 遠端服務目標」部分，按一下「新增 Apigee 遠端服務目標」。
5. 在 Apigee 遠端服務目標對話方塊中，新增下列值：

   屬性	值	說明
   目標名稱	輸入目標服務的名稱。例如：httpbin.org	由 Envoy Proxy 負責的目標端點。
   API 代理	remote-service	在 Envoy 轉接程式安裝期間，在 Apigee 上佈建的 remote-service Proxy。
   路徑	輸入 /resource_path 以比對特定路徑。例如：/httpbin。	在目標端點上比對的要求路徑。這個路徑的 API Proxy 呼叫會與這個 API 產品相符。

6. 按一下 [儲存]。

4. 可建立開發人員應用程式

1. 在側邊導覽選單中，依序選取「發布」>「應用程式」。
2. 按一下「+ 應用程式」。
3. 請按照下列指示填寫「開發人員應用程式」頁面。請等待系統指示後再儲存。

名稱	httpbin-app
顯示名稱	httpbin app
開發人員	選取先前建立的開發人員，或從清單中選擇任何開發人員。

4. 接著，請在應用程式中新增兩項產品：
   1. 首先，請在「憑證」部分中按一下「+ 新增產品」，然後選取剛剛設定的產品：httpbin-product。
   2. 接著，新增 remote-service 產品。您在佈建 Apigee 時，系統會自動建立這個產品。
5. 按一下 [建立]。
6. 在「憑證」下方，按一下「金鑰」旁的「顯示」。
7. 複製 Consumer Key 的值。這個值是您用來向 httpbin 服務呼叫 API 的 API 金鑰。

關於 API 產品

API 產品是 Apigee 遠端服務的主要控制點。建立 API 產品並將其繫結至目標服務時，您會建立一項政策，並套用至您為 Envoy 設定 Apigee 轉接器的任何要求。

API 產品定義

在 Apigee 中定義 API 產品時，您可以設定多個參數，用於評估要求：

• 目標
• 要求路徑
• 配額
• 個 OAuth 範圍

遠端服務目標

如果要求與目標繫結 (例如 httpbin.org) 和要求路徑 (例如 /httpbin) 相符，API 產品定義就會套用至要求。潛在目標清單會儲存在 API 產品的屬性中。

根據預設，Apigee 遠端服務會根據 Envoy 的特殊 :authority (host) 標頭檢查其目標清單；不過，您可以將其設定為使用其他標頭。

API 資源路徑

系統會根據下列規則比對輸入的路徑：

• 單一斜線 (/) 本身會比對任何路徑。
• * 在任何位置都有效，且可在區段內 (斜線之間) 比對。
• ** 在結尾處有效，且會比對任何行結尾。

配額

配額會指定應用程式在 1 小時、1 天、1 週或 1 個月內，可向 API 提交的要求訊息數量。當應用程式達到配額上限時，後續的 API 呼叫就會遭到拒絕。

您可以透過配額，限制用戶端在指定時間內向服務傳送的要求數量。配額通常用於執行與開發人員和合作夥伴的商業合約或服務水準協議，而非用於管理營運流量。舉例來說，您可以使用配額限制免費服務的流量，同時允許付費客戶享有完整存取權。

配額參數是在 API 產品中設定。舉例來說，建立 API 產品時，您可以選擇設定允許的配額限制、時間單位和間隔。

由於 API 金鑰會對應回 API 產品，因此每次驗證 API 金鑰時，系統都可以減少相應的配額計數器 (如果相關聯的產品中定義了配額)。

與 Apigee 執行階段不同，Apigee 遠端服務會自動強制執行產品定義中輸入的配額。如果要求已授權，則要求會計入允許的配額。

配額會由遠端服務程序在本機維護及檢查，並透過 Apigee 執行階段異步維護。這表示如果您有多個維護配額的遠端服務，配額就不會精確，可能會超出一些。如果與 Apigee Runtime 的連線中斷，本機配額會繼續以獨立配額的形式存在，直到能夠重新連線至 Apigee Runtime 為止。

OAuth 範圍

如果您使用 JWT 權杖，可以將權杖限制在允許的 OAuth 範圍子集內。系統會根據 API 產品的範圍，檢查已發出的 JWT 權杖指派的範圍。

關於開發人員應用程式

設定 API 產品後，您將建立與開發人員相關聯的應用程式。應用程式可讓用戶端透過 API 金鑰或 JWT 權杖存取相關的 API 產品。

使用以 JWT 為基礎的驗證機制

您可以使用 JWT 權杖來發出經過驗證的 API Proxy 呼叫，而非使用 API 金鑰。本節說明如何使用 apigee-remote-service-cli token 指令建立、檢查及輪替 JWT 權杖。針對 Apigee 混合式環境，您可以使用這個指令建立 Kubernetes 密鑰來保留 JWT。

總覽

Envoy 會使用其 JWT 驗證篩選器處理 JWT 驗證和驗證作業。

驗證完成後，Envoy ext-authz 篩選器會將要求標頭和 JWT 傳送至 apigee-remote-service-envoy。這項工具會比對 JWT 的 api_product_list 和 scope 宣告與 Apigee API 產品，以便針對要求的目標授權。

建立 Apigee JWT 權杖

您可以使用 CLI 建立 Apigee JWT 權杖：

apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

或者，您也可以使用標準 OAuth 權杖端點。curl 範例：

curl https://org-env.apigee.net/remote-service/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

使用 JWT 權杖

取得權杖後，只要在授權標頭中將權杖傳遞給 Envoy 即可。範例：

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

JWT 權杖失敗

Envoy 拒絕

如果 Envoy 拒絕權杖，您可能會看到類似以下的訊息：

Jwks remote fetch is failed

如果是，請確認 Envoy 設定在 remote_jwks 區段中包含有效的 URI，且 Envoy 可存取該 URI，並在安裝 Apigee Proxy 時正確設定憑證。您應該可以直接使用 GET 呼叫呼叫 URI，並收到有效的 JSON 回應。

範例：

curl --http1.1 https://myorg-eval-test.apigee.net/remote-service/certs

Envoy 傳送的其他訊息可能如下所示：

• 「不允許使用 JWT 中的目標對象」
• 「未設定 JWT 核發者」

這些是 Envoy 設定中可能需要修改的必要條件。

檢查符記

您可以使用 CLI 檢查權杖。範例

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

或

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

偵錯

記錄

您可以調整 $REMOTE_SERVICE_HOME/apigee-remote-service-envoy 服務的記錄層級。所有記錄都會傳送至 stderr。

Envoy 提供記錄功能。如需更多資訊，請參閱下列 Envoy 說明文件連結：

• 應用程式記錄
• 存取記錄檔
• 使用 GKE 搭配 Stackdriver 記錄

變更政策密鑰名稱

部署至叢集的 Kubernetes 密鑰包含轉接器需要的憑證，用於驗證與遠端服務 Proxy 的通訊。這個密鑰需要可設定的磁碟區掛接點。根據預設，掛載點為 /policy-secret。如要變更掛載點，請按照下列步驟操作：

1. 執行以下指令：

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

   例如：

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point

2. 在編輯器中開啟 $REMOTE_SERVICE_HOME/samples/istio/hybrid-apigee-remote-service-envoy.yaml。
3. 將掛接點名稱變更為新名稱：

   volumeMounts:
     - mountPath: /config
       name: apigee-remote-service-envoy
       readOnly: true
     - mountPath: /opt/apigee/tls
       name: tls-volume
       readOnly: true
     - mountPath: /my-mount-point
       name: policy-secret
       readOnly: true

4. 儲存檔案並套用至服務中介：

   kubectl apply -f $REMOTE_SERVICE_HOME/samples/istio/hybrid-apigee-remote-service-envoy.yaml

使用網路 Proxy

您可以在 apigee-remote-service-envoy 二進位檔的環境中使用 HTTP_PROXY 和 HTTPS_PROXY 環境變數，插入 HTTP Proxy。使用這些變數時，您也可以使用 NO_PROXY 環境變數，排除透過 Proxy 傳送的特定主機。

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

請注意，Proxy 必須可從 apigee-remote-service-envoy 存取。

關於指標和數據分析

:5001/metrics 提供 Prometheus 指標端點。您可以設定這個通訊埠編號。請參閱「設定檔」。

Envoy 數據分析

以下連結提供有關取得 Envoy 代理伺服器分析資料的資訊：

• 管理員介面
• 統計資料
• 叢集統計資料

Istio 數據分析

以下連結提供有關取得 Envoy 代理伺服器分析資料的資訊：

• 觀測工作
• 遙測設定

Apigee 數據分析

Envoy 的 Apigee 遠端服務會將要求統計資料傳送至 Apigee，以便進行數據分析。Apigee 會以相關 API 產品名稱回報這些要求。

如要瞭解 Apigee Analytics，請參閱「Analytics 服務總覽」。