將 API 流量資料上傳至 Apigee - Beta 版

Private Cloud 適用的 Edge 4.17.09 版

所有 Edge for Private Cloud 客戶都必須向 Apigee 提交 API Proxy 流量統計資料。Apigee 建議客戶每天上傳一次該資訊，或許可以建立 Cron 工作。

您必須提交正式版 API 部署作業的資料，但不必提交處於開發或測試部署作業階段的 API 資料。在大多數 Edge 安裝作業中，您會為實際工作環境 API 定義特定機構或環境。您提交的資料僅適用於這些實際工作環境機構和環境。

為協助您上傳這類資料，Apigee 提供 apigee-analytics-collector 指令列公用程式的 Beta 版。這個公用程式會將 API 呼叫量報表傳回給 Apigee。每個私人雲端安裝的 Edge 都能使用這項公用程式，擷取並回報流量資料給 Apigee。

存取 apigee-analytics-collector 上傳的資料

使用 apigee-analytics-collector 公用程式上傳資料後，即可在 Apigee 360 中查看。

如要查看資料，請登入 Apigee 360，然後選取「用量」選項。「使用情形」頁面會顯示使用情形圖表，以及每個 Edge 機構的使用情形資料表格。

安裝 apigee-analytics-collector

apigee-analytics-collector 公用程式是透過 apigee-service 公用程式安裝的 RPM。

安裝位置

您安裝 apigee-analytics-collector 公用程式的節點可以是任何可存取 Edge 管理伺服器上的 Edge 管理 API 的節點。您可以直接在管理伺服器、Edge 安裝的另一個節點，或獨立節點上安裝，只要該節點可以向管理伺服器提出 API 要求即可。

網路存取需求

在可存取外部網際網路的機器上安裝 apigee-analytics-collector 公用程式。接著，apigee-analytics-collector 公用程式可將資料直接上傳至 Apigee。

如果沒有節點同時具備 Edge Management Server 上的 Edge Management API 存取權，且沒有外部網際網路存取權，您可以使用 Edge Management API 將流量資料儲存在本機。接著，您必須將資料轉移至可上網的機器，才能上傳至 Apigee。在這種情況下，您不需要使用 apigee-analytics-collector 公用程式。詳情請參閱下方的「手動將資料上傳至 Apigee」一節。

安裝

使用下列指令安裝 apigee-analytics-collector 公用程式。由於您要安裝 RPM 檔案，因此必須由超級使用者或具備完整 sudo 存取權的使用者執行這項指令。對於完整的 sudo 存取權，這表示使用者具備 sudo 存取權，可執行與 root 相同的作業。

> /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector install

執行 apige-analytics-collector

本節說明如何執行 apigee-analytics-collector 公用程式。

設定使用者以執行 apigee-analytics-collector

您必須以非超級使用者的身分執行 apigee-analytics-collector。這位使用者必須具備「apigee」使用者的完整 sudo 存取權。

如要設定使用者擁有「apigee」使用者的完整 sudo 存取權，請使用「visudo」指令編輯 sudoers 檔案，新增以下內容：

analyticsUser        ALL=(apigee)      NOPASSWD: ALL

其中 analyticsUser 是執行 apigee-analytics-collector 公用程式的使用者名稱。

安裝 apigee-analytics-collector 公用程式並設定使用者後，您可以執行 apigee-analytics-collector 公用程式的說明指令，測試該公用程式：

> /opt/apigee/apigee-service/bin/ apigee-service apigee-analytics-collector export traffic --help

執行 apigee-analytics-collector 所需的資訊

您需要下列資訊，才能執行 apigee-analytics-collector 指令，並將資料轉送至 Apigee：

  • apigee_mgmt_api_uri：管理伺服器上 Edge API 的基準網址。這個網址通常會採用以下格式：
    http://ms_IP:8080/v1

    其中 ms_IP 是 IP 位址或管理伺服器，而 8080 是 Edge API 使用的通訊埠。如果您為 Edge API 建立 DNS 項目，網址的格式如下：
    http://ms_DNS/v1

    如果您在 Edge 管理 API 上啟用 TLS，網址的格式如下：
    https://ms_IP:8080/v1
    https://ms_DNS/v1
  • apigee_mgmt_api_email：有權存取 Edge /stats API 的帳戶電子郵件地址。這通常是 Edge 系統管理員的電子郵件，或正式環境機構機構管理員的電子郵件地址。
  • apigee_mgmt_api_password：apigee_mgmt_api_email 指定帳戶的 Edge 密碼。
  • apigee_analytics_client_id 和 apigee_analytics_secret： 上傳資料至 Apigee 的憑證。請向 Apigee 支援團隊提交支援單，以取得 apigee_analytics_client_id 和 apigee_analytics_secret。

範例指令

以下顯示的範例指令是擷取 Edge 安裝中的所有機構和環境的流量資料，並將資料上傳至 Apigee。請注意如何使用 apigee-service 執行 apigee-analytics-collector 指令：

>  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

請注意，指令包含所有必要資訊，例如 apigee_analytics_client_id 和 apigee_analytics_secret。

您應該會看到以下格式的結果：

[
  {
    "org": "myOrg",
    "env": "prod",
    "time_range_start": "08/27/2016 00:00",
    "time_range_end": "08/30/2016 00:00",
    "response": [
      {
        "store_org_env_metrics_hourly_v4": 1
      }
    ]
  },
  {
    "org": "VALIDATE",
    "env": "test",
    "time_range_start": "08/27/2016 00:00",
    "time_range_end": "08/30/2016 00:00",
    "response": [
      {
        "store_org_env_metrics_hourly_v4": 1
      }
    ]
  }
]

使用指令列選項來控制指令的動作。請使用下列選項，指定要納入產生資料的機構和環境：

  • -i, --include_orgs <以半形逗號分隔的項目清單>
  • -x, --exclude_orgs <以半形逗號分隔的項目清單>
  • -n, --include_envs <以半形逗號分隔的項目清單>
  • -e, --exclude_envs <以半形逗號分隔的項目清單>

舉例來說，如要只指定實際工作環境中的機構和環境，請使用 -i (或 --include_orgs) 和 -n (或 --include_envs) 選項：

>  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

在這個範例中，您只會從 myOrg 的正式環境收集資料。

如要將資料轉儲至螢幕，以便在傳送至 Apigee 之前進行檢查，請使用 -S 選項：

>  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod -S \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

-S 選項會略過將資料上傳至 Apigee 的動作。接著重新執行指令，而不使用 -S 選項將資料傳送至 Apigee。

使用 -S 選項的其中一個原因是，就可以在本機顯示不同類型的資料。Apigee 只要求您上傳 API 流量資料，但 -D 選項可讓您顯示 API 產品、開發人員、應用程式或 API Proxy 的資料。以下範例使用 -D 和 -S 選項，在本機顯示開發人員資料：

>  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod -S -D devs \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

加入 -v 選項可取得詳細輸出內容，加入 -R 選項則可查看 apigee-analytics-collector 產生的 curl 指令：

 >  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod -S -R -v \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

下一節將列出完整的命令列選項清單。

指令參數

下表列出 apigee-analytics-collector 公用程式的完整選項：

指令

使用

-h、--help

輸出使用資訊

-D, --dimension <dimension>

要收集的流量維度。有效的維度：apiproducts、devs、apps、apiproxy (預設)

-d, --days <days>

自目前日期算起的過去天數，代表要收集的資料天數。預設值為 3。

如果您指定 -d，請勿同時指定 -s 和 -z 來設定時間範圍。

-m、--apigee_mgmt_api_uri &lt;apigee_mgmt_api_uri&gt;

Edge Management API 的網址。

-u, --apigee_mgmt_api_email <apigee_mgmt_api_email>

具備 Edge /stats API 存取權的帳戶電子郵件地址。這通常是 Edge 系統管理員的電子郵件地址，或是貴機構的正式組織管理員電子郵件地址。

-p, --apigee_mgmt_api_password <apigee_mgmt_api_password>

與 -u 指定的 Edge Management API 電子郵件帳戶相關聯的密碼。

-i, --include_orgs <items>

以半形逗號分隔的機構清單，用於輸出內容。

-x、--Exclude_orgs <items>

要從輸出內容中排除的機構清單 (以半形逗號分隔)。

-n, --include_envs <items>

要包含在輸出內容中的環境清單 (以半形逗號分隔)。

-e、--Exclude_envs <items>

以半形逗號分隔的清單，列出要從輸出內容中納入的環境。

-o, --output <path>

輸出內容的路徑和檔案名稱。

-s, --time_range_start <time_range_start>

查詢流量統計資料的起始時間範圍，格式為「03/01/2016 00:00」。

如果您指定 -d，則請勿同時指定 -s 和 -z 來設定時間範圍。

-z, --time_range_end <time_range_end>

查詢流量統計資料的時間範圍結束時間，格式為「04/01/2016 24:00」。

如果指定 -d，請勿同時指定 -s 和 -z 來設定時間範圍。

-t、--time_unit <time_unit>

流量資料的時間單位。預設週。預設單位 (以小時為單位)。有效的時間單位： 秒、分鐘、小時、天、週。

-S, --standard_output

將輸出內容寫入終端機 (stdout)，而非上傳至 Apigee。

-c, --apigee_analytics_client_id <apigee_analytics_client_id>

將資料上傳至 Apigee 的 ID。如要取得此資訊，請向 Apigee 支援團隊提交支援單。

-r, --apigee_analytics_secret <apigee_analytics_secret>

用於上傳資料至 Apigee 的密鑰。請向 Apigee 支援提交支援單，即可取得相關資訊。

-R、--include_curl_commands

在輸出內容中加入產生的 cURL 指令，以利偵錯。

-v、--verbose

顯示詳細輸出。

手動將資料上傳至 Apigee

Apigee 建議您在具備外部網際網路存取權的機器上安裝 apigee-analytics-collector 公用程式。接著，apigee-analytics-collector 公用程式可將資料直接上傳至 Apigee。

不過，如果機器無法存取外部網際網路，請使用 Edge 管理 API 收集流量資料，然後使用 cURL 指令，從可存取網際網路的機器將資料上傳至 Apigee。您必須針對 Edge 安裝作業中的每個實際執行機構和環境重複執行這項程序。

使用以下 cURL 指令，針對特定機構和環境收集指定時間間隔的流量資料：

curl -X GET -u apigee_mgmt_api_email:apigee_mgmt_api_password \
"http://<ms_IP>:8080/v1/organizations/{org_name}/environments/{env_name}/stats/?select=sum(message_count)&timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM"

這個指令會使用 Edge Get API 訊息數量 API。在這個指令中：

  • apigee_mgmt_api_email:apigee_mgmt_api_password 可以指定擁有 Edge /stats API 存取權的帳戶電子郵件地址。
  • <ms_IP> 是 Edge 管理伺服器的 IP 位址或 DNS 名稱。
  • {org_name} 和 {env_name} 會指定機構和環境。
  • MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM 指定要收集的統計資料時間範圍。請注意，cURL 指令會使用十六進制代碼 %20 表示時間範圍中的空格。

舉例來說，如要收集 24 小時內的統計資料，請使用下列指令：

curl -X GET -u apigee_mgmt_api_email:apigee_mgmt_api_password \
"http://192.168.56.103:8080/v1/organizations/myOrg/environments/prod/stats/?select=sum(message_count)&timeRange=08/29/2016%2000:00~08/30/2016%2000:00"

回應的格式如下：

{
  "environments" : [ {
    "metrics" : [ {
      "name" : "sum(message_count)",
      "values" : [ "42.0" ]
    } ],
    "name" : "prod"
  } ],
  "metaData" : {
    "errors" : [ ],
    "notices" : [ "query served by:53dab80c-e811-4ba6-a3e7-b96f53433baa", "source pg:6b7bab33-e732-405c-a5dd-4782647ce096", "Table used: myorg.prod.agg_api" ]
  }
}

接著，請使用下列 cURL 指令，從可存取網際網路的電腦將資料上傳至 Apigee：

curl -X POST -H 'Content-Type:application/json' \
-u apigee_analytics_client_id:apigee_analytics_secret \
https://nucleus-api-prod.apigee.com/v1/apigee-analytics-cli-api/traffic/orgs/{org_name}/apis -d '{"environments"...}'

其中：

  • apigee_analytics_client_id:apigee_analytics_secret 指定您從 Apigee 支援團隊取得的憑證，用於將資料上傳至 Apigee。
  • {org_name} 會指定機構。
  • {"environments"...} 包含您用於收集上述統計資料的 cURL 指令結果。