作業指南

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

如何取得 API 金鑰

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

1. 登入 Apigee

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

2. 可建立開發人員

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

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

3. 可建立 API 產品

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

  1. 在側邊導覽選單中，依序選取「發布」>「API 產品」。
  2. 點選「+建立」。
  3. 請按照下列指示填寫「產品詳細資料」頁面。請勿點選「儲存」，直到系統指示為止。
    欄位 值
    名稱 httpbin-product
    顯示名稱 httpbin product
    環境 your_environment

    請將此值設為您使用 apigee-remote-service-cli 佈建 Apigee Adapter for Envoy 時所用的環境。
    存取權 Private
    配額 每分鐘 5 個要求

    另請參閱「關於 API 產品」。

  4. 在「自訂屬性」部分，按一下「+新增自訂屬性」。
  5. 輸入這個名稱/值配對：
    • 名稱：輸入這個屬性名稱：apigee-remote-service-targets
    • 值：輸入目標服務的名稱。例如：httpbin.org
  6. 按一下 [確定]。
  7. 按一下 [儲存]。

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

  1. 在側邊導覽選單中，依序選取「發布」>「應用程式」。
  2. 按一下「+ 應用程式」。
  3. 按照下列指示填寫「開發人員應用程式」頁面。請勿儲存，直到系統顯示通知為止。
    4. 名稱 httpbin-app
    顯示名稱 httpbin app
    開發人員 選取先前建立的開發人員，或從清單中選擇任何開發人員。
  4. 在「憑證」部分中，按一下「+ 新增產品」，然後選取剛設定的產品：httpbin-product。
  5. 點選「建立」。
  6. 在「憑證」下方，按一下「金鑰」旁邊的「顯示」。
  7. 複製消費者金鑰的值。這個值是您用來向 httpbin 服務發出 API 呼叫的 API 金鑰。

關於 API 產品

API 產品是 Apigee Remote Service 的主要控制點。 建立 API 產品並繫結至目標服務時，您會建立一項政策，這項政策會套用至您設定 Apigee Adapter for Envoy 處理的任何要求。

API 產品定義

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

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

遠端服務目標

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

根據預設，Apigee Remote Service 會根據目標清單檢查 Envoy 的特殊 :authority (host) 標頭，但您可以設定使用其他標頭。

API 資源路徑

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

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

配額

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

配額使用案例

配額可讓您在指定時間內，對用戶端可向服務發出的要求數量強制設限。配額通常用於強制執行與開發人員和合作夥伴簽訂的商業合約或服務水準協議，而非用於管理作業流量。舉例來說，配額可用於限制免費服務的流量，同時允許付費客戶完整存取。

配額是在 API 產品中定義

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

在 Apigee 使用者介面中設定配額限制。>

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

與 Apigee 執行階段不同，在產品定義中輸入的配額會由 Apigee Remote Service 自動強制執行。如果要求獲得授權，系統會將要求計入允許的配額。

配額的維護位置

配額由遠端服務程序在本機維護及檢查，並與 Apigee 執行階段非同步維護。也就是說，如果有多個維護配額的遠端服務，配額就不會精確，且可能會有部分超出。如果與 Apigee 執行階段的連線中斷，在重新連線至 Apigee 執行階段之前，本機配額會繼續做為獨立配額。

OAuth 範圍

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

關於開發人員應用程式

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

使用以 JWT 為基礎的驗證

您可以使用 JWT 權杖發出經過驗證的 API Proxy 呼叫，不必使用 API 金鑰。本節說明如何使用 apigee-remote-service-cli token 指令建立、檢查及輪替 JWT 權杖。在 Apigee Hybrid 環境中，您可以使用這項指令建立 Kubernetes Secret，以保存 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 https://myorg-eval-test.apigee.net/remote-service/certs

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

  • 「Audiences in Jwt are not allowed」(不允許使用 JWT 中的目標對象)
  • 「Jwt issuer is not configured」(未設定 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 有效層級：debug、info、warn、error。 調整記錄層級。預設值：info
-j, --json-log 以 JSON 記錄的形式發出記錄輸出內容。

Envoy 提供記錄功能。詳情請參閱下列 Envoy 說明文件連結：

變更政策密鑰名稱

部署至叢集的 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. 在編輯器中開啟 $CLI_HOME/samples/apigee-envoy-adapter.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/apigee-envoy-adapter.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 存取。

指標和數據分析簡介

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

Envoy 分析

如要瞭解如何取得 Envoy Proxy Analytics 資料，請參閱下列連結：

Istio 數據分析

如要瞭解如何取得 Envoy Proxy Analytics 資料，請參閱下列連結：

Apigee 數據分析

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

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