作業指南

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

如何取得 API 金鑰

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

1. 登入 Apigee

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

2. 可建立開發人員

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

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

3. 可建立 API 產品

按照下方的產品建立範例操作。另請參閱關於 API 產品設定

  1. 在側邊導覽選單中,依序選取「Publish」(發布) >「API Products」(API 產品)
  2. 按一下「+ API 產品」
  3. 按照下列方式填寫「產品詳細資料」頁面。除非另有指示,否則請勿點選「儲存」
  4. 欄位
    名稱 httpbin-product
    顯示名稱 httpbin product
    環境 your_environment

    請設為您用 apigee-remote-service-cli 佈建 Envoy 的 Apigee Adapter for Envoy 時使用的環境。

    存取權 Private
    配額 每分鐘 5 個要求

    另請參閱瞭解配額

  5. 在「Apigee 遠端服務目標」專區中,按一下「新增 Apigee 遠端服務目標」
  6. 在 Apigee 遠端服務目標對話方塊中,新增下列值:
    屬性 說明
    目標名稱 輸入目標服務的名稱。例如:httpbin.org Envoy Proxy 優先的目標端點。
    API Proxy remote-service 在 Envoy Adapter 安裝期間,在 Apigee 上佈建的 remote-service Proxy。
    路徑 輸入 /resource_path 以比對特定路徑。例如:/httpbin 要在目標端點上比對的要求路徑,對此路徑的 API Proxy 呼叫會與這項 API 產品相符。

    Edge 公開或私人雲端 :以下螢幕截圖顯示 httpbin.org 目標的正確配置對話方塊設定 (適用於 Apigee Edge 公用或私人雲端的適當設定)。

  7. 點按「儲存」

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

  1. 在側邊導覽選單中,依序選取「發布」>「應用程式」
  2. 按一下「+ 應用程式」
  3. 按照下列方式填寫「開發人員應用程式」頁面。除非另有指示,否則請勿儲存。
  4. 名稱 httpbin-app
    顯示名稱 httpbin app
    開發人員 選取您先前建立的開發人員,或從清單中選擇任何開發人員。
  5. 接著,在應用程式中新增兩項產品:
    1. 首先,在「憑證」部分按一下「+ 新增產品」,然後選取您剛設定的產品:httpbin-product
    2. 然後新增 remote-service 產品。這項產品會在您佈建 Apigee 時自動建立。
  6. 點選「建立」
  7. 在「Credentials」(憑證) 下方,按一下「Key」(金鑰) 旁的「Show」(顯示)
  8. 複製消費者金鑰的值。這個值是您將用來對 httpbin 服務進行 API 呼叫的 API 金鑰

關於 API 產品

API 產品是 Apigee 遠端服務的主要控制點。建立 API 產品並繫結至目標服務後,您將建立政策,並套用至設定 Apigee Adapter for Envoy 來處理的所有要求。

API 產品定義

在 Apigee 中定義 API 產品時,您可以設定幾個要用來評估要求的參數:

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

遠端服務目標

如果要求同時與目標繫結 (例如 httpbin.org) 和要求路徑 (例如 /httpbin) 相符,API 產品定義就會套用至要求。可能的目標清單會以屬性的形式儲存在 API 產品上。

根據預設,Apigee 遠端服務會根據目標清單檢查 Envoy 的特殊 :authority (host) 標頭,但可設為使用其他標頭。

API 資源路徑

輸入的路徑符合下列規則:

  • 只有一個斜線 (/) 本身會與任何路徑相符。
  • * 是有效的任何位置,且在特定區段內相符 (斜線之間)。
  • ** 是有效值,且與行結尾的任何項目相符。

配額

配額會指定應用程式在一個小時、一天、一週或一個月內可提交至 API 的要求訊息數量。當應用程式達到配額限制時,系統會拒絕後續的 API 呼叫。

配額用途

配額可讓您強制執行用戶端在一段時間內可對服務發出的要求數量。配額通常用於強制與開發人員和合作夥伴簽署商業合約或服務水準協議,而非管理營運流量。舉例來說,某項配額可能會用來限制免費服務的流量,同時讓付費客戶擁有完整存取權。

配額定義於 API 產品中

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

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

與 Apigee 執行階段不同,Apigee 遠端服務會自動強制執行在產品定義中輸入的配額。如果要求獲得授權,系統就會將該要求計入允許的配額。

配額維護位置

配額會由遠端服務程序在本機維護及檢查,並透過 Apigee 執行階段以非同步方式維護。這表示配額不會精準計算,如果您有多個遠端服務會同時保留該配額,配額可能會遭到超出上限。如果與 Apigee 執行階段的連線中斷,本機配額會繼續採用獨立配額,直到可重新連線至 Apigee 執行階段為止。

OAuth 範圍

如果您使用的是 JWT 權杖,可以將權杖限制為允許的 OAuth 範圍子集。系統會根據 API 產品的範圍,檢查指派給所核發 JWT 權杖的範圍。

關於開發人員應用程式

設定 API 產品後,您就能建立與開發人員相關聯的應用程式。應用程式允許用戶端透過 API 金鑰或 JWT 權杖存取相關聯的 API 產品。

使用 JWT 式驗證

您可以使用 JWT 憑證來進行經過驗證的 API Proxy 呼叫,而不使用 API 金鑰。本節說明如何使用 apigee-remote-service-cli token 指令建立、檢查及輪替 JWT 權杖。

總覽

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

驗證完成後,Envoy ext-authz 篩選器會將要求標頭和 JWT 傳送至 apigee-remote-service-envoy。此憑證會比對 JWT 的 api_product_listscope 憑證附加資訊,以及 Apigee API 產品,藉此依據要求的目標授權 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 權杖

取得權杖後,只要將權杖傳送至 Authorization 標頭中的 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 https://myorg-eval-test.apigee.net/remote-service/certs

來自 Envoy 的其他訊息可能如下所示:

  • 「不得使用 ZHT 指定的目標對象」
  • 「未設定 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

偵錯

請參閱「有效的 API 金鑰失敗」一節。

記錄

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

元素 需要 說明
-l、--log-level 有效等級:偵錯、資訊、警告、錯誤。 調整記錄層級。預設:資訊
-j、--json-log 將記錄輸出做為 JSON 記錄。

Envoy 提供記錄服務。詳情請參閱下列 Envoy 說明文件連結:

使用網路 Proxy

您可以使用 HTTP_PROXY 和 HTTPS_PROXY 二進位檔環境中的 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 Proxy 分析資料,請點選下列連結:

Istio 數據分析

如要瞭解如何取得 Envoy Proxy 分析資料,請點選下列連結:

Apigee 數據分析

Apigee Remote Service for Envoy 會將要求統計資料傳送至 Apigee 進行數據分析處理。Apigee 會在相關聯的 API 產品名稱下方回報這些要求。

如要瞭解 Apigee 數據分析,請參閱 Analytics (分析) 服務總覽