本頁面由 Cloud Translation API 翻譯而成。

從 Analytics 匯出資料

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

查看 Apigee Edge 說明文件。

Apigee Analytics 會收集及分析 API 傳輸的各種資料，並提供視覺化工具，包括互動式資訊主頁、自訂報表和其他工具，可找出 API Proxy 效能趨勢。

現在，您可以將 Apigee Analytics 的分析資料匯出至自己的資料存放區 (例如 Google Cloud Storage 或 Google BigQuery)，解鎖這些豐富的內容。接著，您就能運用 Google BigQuery 和 TensorFlow 提供的強大查詢和機器學習功能，自行進行資料分析。您也可以將匯出的 Analytics 資料與其他資料 (例如網頁記錄) 合併，進一步瞭解使用者、API 和應用程式。

支援哪些匯出資料格式？

將數據分析資料匯出為下列其中一種格式：

逗號分隔值 (CSV)

預設分隔符號為半形逗號 (,)。支援的分隔符號包括半形逗號 (,)、直立線 (|) 和 Tab 鍵 (\t)。使用 csvDelimiter 屬性設定值，詳情請參閱「匯出要求屬性參考資料」。
JSON (以換行符號分隔)

允許使用換行字元做為分隔符。

匯出的資料包括 Apigee 內建的所有 Analytics 指標和維度，以及您新增的任何自訂 Analytics 資料。如要瞭解匯出資料的說明，請參閱「數據分析指標、維度和篩選器參考資料」。

您可以將 Analytics 資料匯出至下列資料存放區：

匯出數據分析資料的步驟

以下步驟摘要說明匯出數據分析資料的程序：

設定資料存放區 (Cloud Storage 或 BigQuery)，以匯出資料。請務必確認資料存放區已正確設定，且用於將資料寫入資料存放區的 Apigee 服務代理程式服務帳戶具備正確權限。

建立資料存放區，定義要匯出資料的資料存放區 (Cloud Storage 或 BigQuery) 屬性。

匯出數據分析資料。資料匯出作業會在背景非同步執行。

查看匯出要求狀態，判斷匯出作業何時完成。

匯出作業完成後，您可以在資料存放區中存取匯出的資料。

以下各節將詳細說明這些步驟。

設定資料存放區

設定 Cloud Storage 或 BigQuery，以啟用分析資料匯出功能。

設定 Google Cloud Storage

如要將資料匯出至 Google Cloud Storage，請先完成下列步驟：

建立 Google Cloud Storage bucket。
確認 Google Cloud Platform 專案已啟用 BigQuery API。匯出至 Cloud Storage 時，Apigee 會使用 BigQuery API 來運用 BigQuery 匯出功能。

如需操作說明，請參閱「啟用 API」。
請確認電子郵件地址為 service-project-number@gcp-sa-apigee.iam.gserviceaccount.com 的「Apigee 服務代理」服務帳戶已獲派下列角色：
- BigQuery 工作使用者
- 儲存空間管理員
注意：如果服務帳戶已存在，您不需要建立新帳戶，只要視需要變更現有帳戶的角色即可。

專案首頁會列出 project-number，如下所示。

請參閱「授予、變更及撤銷資源的存取權」。

或者，如要修改現有角色或建立自訂角色，請為角色新增下列權限：
- bigquery.jobs.create
- storage.objects.create
- storage.objects.delete
- storage.objects.list
注意： 變更服務帳戶的角色後，必須等待一分鐘以上，變更才會生效。

設定 Google BigQuery

將資料匯出至 Google BigQuery 前，請先完成下列步驟：

確認已在 Google Cloud Platform 專案中啟用 BigQuery。
確認 Google Cloud Platform 專案已啟用 BigQuery API。如需操作說明，請參閱「啟用 API」。
請確認電子郵件地址為 service-project-number@gcp-sa-apigee.iam.gserviceaccount.com 的「Apigee 服務代理」服務帳戶已獲派下列角色：
- BigQuery 工作使用者
- BigQuery 資料編輯者
注意：如果服務帳戶已存在，您不需要建立新帳戶，只要視需要變更現有帳戶的角色即可。

專案首頁會列出 project-number，如下所示。

請參閱「授予、變更及撤銷資源的存取權」。

如要修改現有角色或建立自訂角色，請為角色新增下列權限：
- bigquery.datasets.create
- bigquery.datasets.get
- bigquery.jobs.create
- bigquery.tables.create
- bigquery.tables.get
- bigquery.tables.updateData
注意： 變更服務帳戶的角色後，必須等待一分鐘以上，變更才會生效。
建立 BigQuery 資料集。

將資料匯出至美國或歐盟的個別區域 BigQuery

由於美國或歐盟的 Analytics 資料會儲存在美國或歐盟多區域，因此您無法直接將資料匯出至 BigQuery 中的個別美國或歐盟區域。如要解決這個問題，可以先將資料匯出至 Google Cloud Storage，然後按照下列步驟將資料移轉至 BigQuery：

建立 Cloud Storage bucket，並將「位置」設為美國或歐盟的個別區域，與 BigQuery 中的資料建立關聯。
使用上一個步驟建立的儲存空間 bucket，建立 Cloud Storage 資料儲存庫。
將資料匯出至 Cloud Storage。如需範例，請參閱下方的「範例 1：將資料匯出至 Cloud Storage」。
如要將資料載入 BigQuery，請參閱下列章節：
- 從 Cloud Storage 載入 CSV 資料
- 從 Cloud Storage 載入 JSON 資料

管理資料儲存庫

資料存放區會定義與匯出資料存放區 (Cloud Storage、BigQuery) 的連線。

下列各節說明如何建立及管理資料存放區。建議您先測試資料存放區設定，再建立資料存放區。

測試資料存放區設定

建立資料存放區時，Apigee 不會測試或驗證設定是否有效。也就是說，您可以建立資料存放區 (在下一個步驟中)，但要等到第一次執行資料匯出作業時，才會偵測到任何錯誤。

資料匯出程序可能需要很長時間才能執行，因此您可以先測試資料存放區設定是否有效，並在建立資料存放區前修正所有錯誤，以便更快偵測到錯誤。

如要測試資料存放區設定，請對 /organizations/{org}/analytics/datastores:test API 發出 POST 要求。在要求主體中傳遞下列資訊：

顯示名稱
資料儲存庫類型
根據資料儲存庫類型設定詳細資料，如「資料儲存庫要求屬性參考資料」一文所述。

舉例來說，下列程式碼會測試 Cloud Storage 資料存放區設定：

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores:test" \
  -X POST \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "displayName": "My Cloud Storage datastore",
    "targetType": "gcs",
    "datastoreConfig": {
      "projectId": "my-project",
      "bucketName": "my-bucket",
      "path": "my/analytics/path"
    }
  }'

如果測試成功，回應範例如下：

{
  "state": "completed",
}

以下是測試失敗時的回應範例：

{
  "state": "failed",
  "error": "<error message>"
}

在這種情況下，請解決錯誤訊息中提出的問題，然後重新測試資料存放區設定。測試成功後，請按照下一節的說明建立資料存放區。

建立資料儲存庫

如要建立資料存放區，請對 /organizations/{org}/analytics/datastores API 發出 POST 要求。在要求主體中傳遞下列資訊：

顯示名稱
資料儲存庫類型
根據資料儲存庫類型設定詳細資料，如「資料儲存庫要求屬性參考資料」一文所述。

以下提供各資料儲存區類型的範例。

以下是 Cloud Storage 資料存放區的回應範例：

{
    "self": "/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b",
    "displayName": "My Cloud Storage datastore",
    "org": "myorg",
    "targetType": "gcs",
    "createTime": "1535411583949",
    "lastUpdateTime": "1535411634291",
    "datastoreConfig": {
          "projectId": "my-project",
          "bucketName": "my-bucket",
          "path": "my/analytics/path"
    }
}

如要查看資料存放區詳細資料，請使用 self 屬性中傳回的網址，詳情請參閱「查看資料存放區詳細資料」。

詳情請參閱「建立資料存放區 API」。

範例 1：建立 Cloud Storage 資料存放區

下列要求會建立 Cloud Storage 資料存放區：

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores" \
  -X POST \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "displayName": "My Cloud Storage datastore",
    "targetType": "gcs",
    "datastoreConfig": {
      "projectId": "my-project",
      "bucketName": "my-bucket",
      "path": "my/analytics/path"
    }
  }'

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一文所述。如要瞭解本範例使用的 curl 選項，請參閱「使用 curl」。如要瞭解可使用的環境變數，請參閱為 Apigee API 要求設定環境變數。

範例 2：建立 BigQuery 資料儲存庫

下列要求會建立 BigQuery 資料存放區：

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores" \
  -X POST \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "displayName": "My BigQuery datastore",
    "targetType": "bigquery",
    "datastoreConfig": {
      "projectId": "my-project",
      "datasetName": "mybigquery",
      "tablePrefix": "bqprefix"
    }
  }'

查看所有資料存放區

如要查看貴機構的所有資料存放區，請向 /organizations/{org}/analytics/datastores API 發出 GET 要求。

例如：

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

以下是回應範例：

{
  "datastores": [
  {
    "self": "/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b",
    "displayName": "My Cloud Storage datastore",
    "org": "myorg",
    "targetType": "gcs",
    "createTime": "1535411583949",
    "lastUpdateTime": "1535411634291",
    "datastoreConfig": {
          "projectId": "my-project",
          "bucketName": "my-bucket",
          "path": "my/analytics/path"
    }
  },
  {
    "self": "/organizations/myorg/analytics/datastores/g8c3f0mk-1f78-8837-9c67-k222b60ce30b",
    "displayName": "My BigQuery datastore",
    "org": "myorg",
    "targetType": "bigquery",
    "createTime": "1535411583949",
    "lastUpdateTime": "1535411634291",
    "datastoreConfig": {
      "projectId": "my-project",
      "datasetName": "mybigquery",
      "tablePrefix": "bqprefix"
    }
  }
  ]
}

詳情請參閱列出資料存放區 API。

查看資料儲存區的詳細資料

如要查看資料存放區的詳細資料，請對 /organizations/{org}/analytics/datastores/{datastore} API 發出 GET 要求。

例如：

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

以下提供 Cloud Storage 資料儲存庫的回應範例：

{
    "self": "/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b",
    "displayName": "My Cloud Storage datastore",
    "org": "myorg",
    "targetType": "gcs",
    "createTime": "1535411583949",
    "lastUpdateTime": "1535411634291",
    "datastoreConfig": {
          "projectId": "my-project",
          "bucketName": "my-bucket",
          "path": "my/analytics/path"
    }
}

詳情請參閱「取得資料存放區 API」。

修改資料儲存區

如要修改資料存放區，請向 /organizations/{org}/analytics/datastores/{datastore} API 發出 PUT 要求。在要求主體中傳遞下列所有或部分資訊：

資料儲存庫顯示名稱
根據資料儲存庫類型設定詳細資料，如「資料儲存庫要求屬性參考資料」一文所述。

舉例來說，如要更新 Cloud Storage 資料存放區：

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b" \
  -X PUT \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "displayName": "My Cloud Storage datastore",
    "datastoreConfig": {
      "projectId": "my-project",
      "bucketName": "my-bucket",
      "path": "my/analytics/path"
    }
  }'

以下提供 Cloud Storage 資料儲存庫的回應範例：

{
    "self": "/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b",
    "displayName": "My Cloud Storage datastore",
    "org": "myorg",
    "targetType": "gcs",
    "createTime": "1535411583949",
    "lastUpdateTime": "1535411634291",
    "datastoreConfig": {
          "projectId": "my-project",
          "bucketName": "my-bucket",
          "path": "my/analytics/path"
    }
}

詳情請參閱「更新資料存放區 API」。

刪除資料儲存庫

如要刪除資料存放區，請向 /organizations/{org}/analytics/datastores/{datastore} API 發出 DELETE 要求。

例如：

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b" \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN"

以下是回應範例：

{}

詳情請參閱刪除資料儲存庫 API。

匯出數據分析資料

如要匯出數據分析資料，請對 /organizations/{org}/environments/{env}/analytics/exports API 發出 POST 要求。在要求主體中傳遞下列資訊：

匯出要求的名稱和說明
匯出資料的日期範圍 (值只能涵蓋一天)
匯出資料的格式
資料儲存庫名稱

以下提供匯出要求的範例。如要完整瞭解要求主體屬性，請參閱匯出要求屬性參考資料。

POST 的回應格式如下：

{
    "self": "/organizations/myorg/environments/test/analytics/exports/a7c2f0dd-1b53-4917-9c42-a211b60ce35b",
    "created": "2017-09-28T12:39:35Z",
    "state": "enqueued"
}

請注意，回應中的 state 屬性已設為 enqueued。POST 要求會以非同步方式運作。也就是說，要求傳回回應後，這項作業仍會在背景執行。state 的可能值包括：enqueued、running、completed、failed。

如要查看資料匯出要求的狀態，請使用 self 屬性中傳回的網址，如「查看 Analytics 匯出要求的狀態」一文所述。要求完成後，回應中的 state 屬性值會設為 completed。然後存取資料存放區中的 Analytics 資料。

詳情請參閱「建立資料匯出 API」。

範例 1：將資料匯出至 Cloud Storage

以下範例會從 myorg 機構的 test 環境，匯出過去 24 小時的完整原始資料集。內容會以 JSON 格式匯出至 Cloud Storage：

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -X POST \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2020-06-08",
      "end": "2020-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }'

使用 self 屬性指定的 URI 監控工作狀態，如「查看 Analytics 匯出要求狀態」一文所述。

範例 2：將資料匯出至 BigQuery

注意：BigQuery 資料集的資料位置必須與 analytics_location 相同。如果您的數據分析區域位於美國或歐盟：

如果該區域位於美國境內，請將「資料位置」設為「美國 (多個美國地區)」。
如果分析區域屬於歐盟，請將「資料位置」設為「eu (多個歐盟境內的地區)」。

以下範例會將以半形逗號分隔的 CSV 檔案匯出至 BigQuery：

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -X POST \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "name": "Export query results to BigQuery",
    "description": "One-time export to BigQuery",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "csv",
    "csvDelimiter": ",", 
    "datastoreName": "My BigQuery data repository"
  }'

注意：匯出的 CSV 檔案會建立 BigQuery 資料表，並使用下列前置字串：

<PREFIX>_<EXPORT_DATE>_api_<UUID>_from_<FROM_DATE>_to_<TO_DATE>

如要監控工作狀態，請使用 self 屬性指定的 URI，詳情請參閱「查看 Analytics 匯出要求的狀態」。

匯出 API 配額簡介

為避免過度使用高成本的資料匯出 API 呼叫，Apigee 會對機構每天呼叫 organizations/{org}/environments/{env}/analytics/exports API 的次數設下 15 次的配額限制。

如果超出呼叫配額，API 會傳回 HTTP 429 回應。

查看所有 Analytics 匯出要求的狀態

如要查看所有 Analytics 匯出要求的狀態，請對 /organizations/{org}/environments/{env}/analytics/exports 發出 GET 要求。

舉例來說，下列要求會傳回 myorg 機構中 test 環境的所有資料分析匯出要求狀態：

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

以下是回應範例，列出兩項匯出要求，其中一項已加入佇列 (已建立並在佇列中)，另一項則已完成：

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To Cloud Storage",
    "description": "One-time export to Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My datastore",
    "executionTime": "36 seconds",
    "created": "2018-09-28T12:39:35Z",
    "updated": "2018-09-28T12:39:42Z",
    "state": "enqueued"
  },
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/9870987089fe03-4364-aaf2-6d4f110444ba"
    "name": "Export raw results to BigQuery",
    "description": "One-time export to BigQuery",
    ... 
  }
]

詳情請參閱列出資料匯出 API。

查看 Analytics 匯出要求的狀態

如要查看特定數據分析匯出要求的狀態，請對 /organizations/{org}/environments/{env}/analytics/exports/{exportId} 發出 GET 要求，其中 {exportId} 是與數據分析匯出要求相關聯的 ID。

注意： 提交匯出要求時，系統會在 self 屬性中傳回用於檢查要求狀態的網址。如要取得數據分析匯出要求 ID，請查看所有數據分析匯出要求及其相關聯 ID 的清單，如「查看所有數據分析匯出要求的狀態」一文所述。

舉例來說，下列要求會傳回 ID 為 4d6d94ad-a33b-4572-8dba-8677c9c4bd98 的 Analytics 匯出要求狀態。

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

以下是回應範例：

{
  "self":
"/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98",
  "name": "Export results to Cloud Storage",
  "description": "One-time export to Cloud Storage",
  "userId": "my@email.com",
  "datastoreName": "My datastore",
  "executionTime": "36 seconds",
  "created": "2018-09-28T12:39:35Z",
  "updated": "2018-09-28T12:39:42Z",
  "state": "enqueued"
}

詳情請參閱「取得資料匯出 API」。

如果分析資料匯出作業未傳回任何分析資料，executionTime 會設為「0 秒」。

Datastore 請求屬性參考資料

下表說明根據資料存放區類型建立資料存放區時，可以 JSON 格式在要求內容中傳遞的屬性。

Google Cloud Storage：

屬性

說明

是否必要

專案 ID

Google Cloud Platform 專案 ID。

如要建立 Google Cloud Platform 專案，請參閱 Google Cloud Platform 說明文件中的「建立及管理專案」。

是

Bucket Name

要匯出 Analytics 資料的 Cloud Storage bucket 名稱。

注意：執行資料匯出作業前，值區必須已存在。

如要建立 Cloud Storage 值區，請參閱 Google Cloud Platform 說明文件中的「建立值區」。

是

路徑

在 Cloud Storage bucket 中儲存 Analytics 資料的目錄。

是

BigQuery：

屬性	說明	是否必要
專案 ID	Google Cloud Platform 專案 ID。如要建立 Google Cloud Platform 專案，請參閱 Google Cloud Platform 說明文件中的「建立及管理專案」。	是
資料集名稱	您要將 Analytics 資料匯出至哪個 BigQuery 資料集。請務必先建立資料集，再要求匯出資料。如要建立 BigQuery 資料集，請參閱 Google Cloud Platform 說明文件中的「建立及使用資料集」。	是
資料表前置字元	在 BigQuery 資料集中為 Analytics 資料建立的資料表名稱前置字串。	是

匯出要求屬性參照

下表說明匯出數據資料時，可以 JSON 格式在要求主體中傳遞的屬性。

屬性	說明	是否必要
`description`	匯出要求說明。	否
`name`	匯出要求名稱。	是
`dateRange`	以 `yyyy-mm-dd` 格式指定要匯出資料的 `start` 和 `end` 日期。例如： "dateRange": { "start": "2018-07-29", "end": "2018-07-30" } `dateRange` 值只能涵蓋一天。日期範圍從 `start`當天的世界標準時間 00:00:00 開始，到 `end`當天的世界標準時間 00:00:00 結束。注意：為確保系統擷取前一天的所有資料，您可能需要延後匯出要求開始時間 (例如世界標準時間凌晨 00:05:00)。	是
`outputFormat`	指定為 `json` 或 `csv`。	是
`csvDelimiter`	CSV 輸出檔案中使用的分隔符號 (如果 `outputFormat` 設為 `csv`)。預設為半形逗號 (,) 字元。支援的分隔符號包括半形逗號 (,)、直立線 (\|) 和 Tab 鍵 (\t)。	否
`datastoreName`	包含資料儲存庫定義的資料儲存庫名稱。	是

例如：

{
  "name": "Export raw results to Cloud Storage",
  "description": "Export raw results to Cloud Storage for last 24 hours",
  "datastoreName": "My Cloud Storage datastore"
}