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

從 Analytics 匯出資料
透過集合功能整理內容你可以依據偏好儲存及分類內容。

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

Apigee Analytics 會收集及分析 API 中流動的大量資料，並提供可視化工具，包括互動式資訊主頁、自訂報表，以及其他可用來找出 API Proxy 效能趨勢的工具。

您現在可以將 Apigee Analytics 中的分析資料匯出至自己的資料存放區 (例如 Google Cloud Storage 或 Google BigQuery)，以便使用這類豐富內容。接著，您就能利用 Google BigQuery 和 TensorFlow 提供的強大查詢和機器學習功能，自行進行資料分析。您也可以將匯出的分析資料與其他資料 (例如網站記錄) 結合，針對使用者、API 和應用程式取得新的洞察資料。

支援哪些匯出資料格式？

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

逗號分隔值 (CSV)

預設分隔符號為半形逗號 (,) 字元。支援的分隔符號包括半形逗號 (,)、直立線 (|) 和制表符號 (\t)。使用 csvDelimiter 屬性設定值，如匯出要求屬性參考資料所述。
JSON (以換行符號分隔)

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

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

您可以將數據分析資料匯出至下列資料存放區：

匯出數據分析資料的步驟

以下步驟概述匯出數據分析資料的程序：

設定資料存放區 (Cloud Storage 或 BigQuery) 以便匯出資料。您必須確保資料存放區已正確設定，且用於將資料寫入資料存放區的 Apigee Service Agent 服務帳戶具備正確的權限。

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

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

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

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

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

設定資料存放區

設定 Cloud Storage 或 BigQuery，以便透過 Analytics 資料匯出功能存取資料。

設定 Google Cloud Storage

您必須先完成下列事項，才能將資料匯出至 Google Cloud Storage：

建立 Google Cloud Storage 值區。
請確認 Google Cloud Platform 專案已啟用 BigQuery API。Apigee 會在匯出至 Cloud Storage 時使用 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

由於美國或歐盟的數據分析資料會儲存在美國或歐盟多區域，因此您無法將資料直接匯出至 BigQuery 中的個別美國或歐盟區域。解決方法是先將資料匯出至 Google Cloud Storage，然後按照下列步驟將資料轉移至 BigQuery：

建立 Cloud Storage 值區，並將位置設為您想與 BigQuery 資料建立關聯的美國或歐盟個別區域。
使用先前步驟建立的儲存值區，建立 Cloud Storage 資料儲存庫。
將資料匯出至 Cloud Storage。如需範例，請參閱下方的範例 1：將資料匯出至 Cloud Storage。
將資料載入 BigQuery，如以下各節所述：
- 從 Cloud Storage 載入 CSV 資料
- 從 Cloud Storage 載入 JSON 資料

管理資料儲存庫

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

下列各節將說明如何建立及管理資料儲存庫。建議您在建立資料儲存庫之前，先測試資料存放區設定。

測試資料存放區設定

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

由於資料匯出程序可能需要很長的時間才能執行，因此您可以先測試資料存放區設定，確保其有效，然後在建立資料儲存庫前修正任何錯誤，以便更快偵測錯誤。

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

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

舉例來說，以下測試會測試 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 要求。請在要求主體中傳遞下列資訊：

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

以下列舉各資料存放區類型的範例。

以下提供 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 屬性中傳回的網址，詳情請參閱「查看資料儲存庫的詳細資料」一文。

詳情請參閱「Create data store 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"
    }
  }
  ]
}

詳情請參閱 List data stores 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 要求。在要求主體中傳遞下列所有資訊或其中一部分：

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

舉例來說，如要更新 Cloud Storage 資料儲存庫，請按照下列步驟操作：

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores" \
  -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"

以下提供回應範例：

{}

詳情請參閱Delete data store 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 屬性中傳回的網址，查看資料匯出要求的狀態。要求完成後，回應中的 state 屬性值會設為 completed。您就能存取資料儲存庫中的分析資料。

詳情請參閱「建立資料匯出 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"
  }'

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

範例 2：將資料匯出至 BigQuery

注意：BigQuery 資料集的資料位置必須與 analytics_location 相同。美國或歐盟的 Analytics 區域：

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

以下範例會將以逗號分隔的 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 匯出要求的狀態」一文。

關於 Export 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": "[email protected]",
    "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",
    ... 
  }
]

詳情請參閱List data exports API。

查看 Analytics 匯出要求的狀態

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

注意： 提交匯出要求時，系統會在 self 屬性中傳回用於檢查要求狀態的網址。如要取得 Analytics 匯出要求的 ID，請查看所有 Analytics 匯出要求清單及其相關 ID，詳情請參閱「查看所有 Analytics 匯出要求的狀態」。

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

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": "[email protected]",
  "datastoreName": "My datastore",
  "executionTime": "36 seconds",
  "created": "2018-09-28T12:39:35Z",
  "updated": "2018-09-28T12:39:42Z",
  "state": "enqueued"
}

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

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

資料儲存庫要求屬性參考資料

下表說明在根據資料儲存庫類型建立資料儲存庫時，您可以以 JSON 格式在要求主體中傳遞的屬性。

Google Cloud Storage：

屬性

說明

是否必要

專案 ID

Google Cloud Platform 專案 ID。

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

是

值區名稱

您要匯出數據分析資料的 Cloud Storage 值區名稱。

注意：必須先建立值區，才能匯出資料。

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

是

路徑

在 Cloud Storage 值區中儲存數據分析資料的目錄。

是

適用於 BigQuery：

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

匯出要求資源參照

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

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

從 Analytics 匯出資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

支援哪些匯出資料格式？

匯出數據分析資料的步驟

設定資料存放區

設定 Google Cloud Storage

設定 Google BigQuery

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

管理資料儲存庫

測試資料存放區設定

建立資料儲存庫

範例 1：建立 Cloud Storage 資料儲存庫

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

查看所有資料儲存庫

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

修改資料儲存區

刪除資料儲存庫

匯出數據分析資料

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

範例 2：將資料匯出至 BigQuery

關於 Export API 配額

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

查看 Analytics 匯出要求的狀態

資料儲存庫要求屬性參考資料

匯出要求資源參照

從 Analytics 匯出資料
透過集合功能整理內容你可以依據偏好儲存及分類內容。