作業指南

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

如何取得 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. 請按照下列指示填寫「產品詳細資料」頁面。請勿點選「儲存」，直到系統提示為止。
    4. 欄位 值
    名稱 httpbin-product
    顯示名稱 httpbin product
    環境 your_environment

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

    另請參閱瞭解配額。
  4. 在「Apigee 遠端服務目標」專區中，按一下「新增 Apigee 遠端服務目標」。
  5. 在 Apigee 遠端服務目標對話方塊中，新增下列值：
    屬性 值 說明
    目標名稱 輸入目標服務的名稱。例如：httpbin.org Envoy Proxy 前方的目標端點。
    路徑 輸入 /resource_path 來比對特定路徑。例如：/httpbin。 在目標端點上比對的要求路徑。這個路徑的 API Proxy 呼叫會與這個 API 產品相符。
  6. 按一下 [儲存]。

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

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

    關於 API 產品

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

    API 產品定義

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

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

    遠端服務目標

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

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

    API 資源路徑

    輸入的路徑會根據下列規則相符：

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

    配額

    配額會指定應用程式在 1 小時、1 天、1 週或 1 個月內，可向 API 提交的要求訊息數量。當應用程式達到配額上限時，後續的 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 權杖。

    總覽

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

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

    建立 Apigee JWT 權杖

    Apigee JWT 權杖可使用 CLI 建立：

    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 傳送的其他訊息可能如下所示：

    • 「不允許使用 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

    偵錯

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

    記錄

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

    元素 必填 說明
    -l、--log-level 有效層級：debug、info、warn、error。 調整記錄層級。預設：資訊
    -j、--json-log 以 JSON 記錄格式產生記錄輸出內容。

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

    使用網路 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 代理伺服器分析資料的資訊：

    Istio 數據分析

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

    Apigee 數據分析

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

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