從 Analytics (分析) 匯出資料

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

為指派的服務專員設定權限

如要為指派的服務專員設定權限，以便因應上述變更，請按照下列步驟操作。

  1. 輸入下列指令，找出 Google Cloud 服務代理程式的名稱：
    curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/ORG" \
  -u email:password \
  | jq -r '.properties.property[] | select(.name=="serviceAgent.analytics") | .value'

    其中 ORG 是貴機構。這會傳回服務代理的名稱和值，如下所示：

    "property" : [
  {
   "name" : "serviceAgent.analytics",
   "value" : "service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com"
   },
  2. 在 Google Cloud 控制台中開啟「IAM」資訊主頁。
  3. 選取 Google Cloud 專案。
  4. 按一下「IAM」窗格頂端的「新增」。
  5. 在「New principals」欄位中，輸入步驟 1 中傳回的服務代理 value。舉例來說，步驟 1 中顯示的 value 為 service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com。
  6. 按一下「+ 新增其他角色」按鈕，然後新增下列角色：
    • BigQuery 使用者
    • Storage 管理員
  7. 按一下 [儲存]。

Apigee 數據分析資料

Apigee Analytics 會收集及分析在 API 中流動的各類資料，並提供可視化工具，包括互動式資訊主頁、自訂報表，以及可找出 API 代理程式效能趨勢的其他工具。您現在可以將 Apigee Analytics 中的分析資料匯出至自有資料存放區 (例如 Google Cloud Storage 或 Google BigQuery)，以便使用這類豐富內容。接著，您就能利用 Google BigQuery 和 TensorFlow 提供的強大查詢和機器學習功能，自行執行資料分析。您也可以將匯出的 Analytics 資料與其他資料 (例如網站記錄) 結合，進一步瞭解使用者、API 和應用程式。

匯出資料格式

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

  • 逗號分隔值 (CSV)

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

  • JSON (以換行符號分隔)

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

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

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

匯出程序總覽

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

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

  2. 建立資料儲存庫，定義匯出資料的資料存放區 (Cloud Storage 或 BigQuery) 屬性，包括用於存取資料存放區的憑證。

    建立資料儲存庫時，您會將資料存放區憑證上傳至 Edge 憑證保管箱，以便安全儲存這些憑證。資料匯出機制會使用這些憑證，將資料寫入資料存放區。

  3. 使用資料匯出 API 啟動資料匯出作業。資料匯出作業會在背景以非同步方式執行。

  4. 使用資料匯出 API 判斷匯出作業何時完成。

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

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

設定資料存放區

資料分析匯出機制會將資料寫入 Cloud Storage 或 BigQuery。如要執行寫入作業，您必須：

  • 建立 Google Cloud Platform 服務帳戶。
  • 設定服務帳戶的角色，讓服務帳戶可以存取 Cloud Storage 或 BigQuery。

為 Cloud Storage 或 BigQuery 建立服務帳戶

服務帳戶是一種 Google 帳戶類型，屬於應用程式，而不是個別使用者。應用程式會使用服務帳戶存取服務。

服務帳戶具有以 JSON 字串表示的服務帳戶金鑰。建立 Edge 資料儲存庫時，您會定義資料存放區的連線，並將這個鍵傳遞給該資料儲存區。資料匯出機制會使用這個金鑰存取資料存放區。

與金鑰相關聯的服務帳戶必須是 Google Cloud Platform 專案擁有者，並具備 Google Cloud Storage 值區的寫入權限。如要建立服務金鑰並下載必要酬載，請參閱 Google Cloud Platform 說明文件中的「建立及管理服務帳戶金鑰」。

舉例來說，您第一次下載金鑰時，系統會將金鑰格式化為 JSON 物件：

{ 
  "type": "service_account", 
  "project_id": "myProject", 
  "private_key_id": "12312312", 
  "private_key": "-----BEGIN PRIVATE KEY-----\n...", 
  "client_email": "client_email@developer.gserviceaccount.com", 
  "client_id": "879876769876", 
  "auth_uri": "https://accounts.google.com/organizations/oauth2/auth", 
  "token_uri": "https://oauth2.googleapis.com/token", 
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2", 
  "client_x509_cert_url": "https://www.googleapis.com" 
}

設定 Google Cloud Storage

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

  • 請確認您的 Google Cloud Platform 專案已啟用 BigQuery 和 Cloud Resource Manager API。如需操作說明，請參閱「啟用 API」。Apigee 會在匯出至 Cloud Storage 時使用 BigQuery API 來運用 BigQuery 匯出功能，並在每次匯出前使用 Cloud Resource Manager API 檢查權限。

  • 請確認服務帳戶已指派下列角色：

    • BigQuery 工作使用者
    • Storage 物件建立者
    • 儲存空間管理員 (僅適用於測試資料儲存空間，如「測試資料儲存空間設定」所述)。如果這個角色的權限範圍太廣，您可以改為在現有角色中新增 storage.buckets.get 權限。

    如要修改現有角色或建立自訂角色，請為角色新增下列權限：

    • bigquery.jobs.create
    • storage.objects.create
    • storage.buckets.get (僅適用於測試資料儲存庫，如測試資料儲存庫設定所述)

設定 Google BigQuery

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

  • 請確認您的 Google Cloud Platform 專案已啟用 BigQuery 和 Cloud Resource Manager API。如需操作說明，請參閱「啟用 API」。Apigee 會在每次匯出前使用 Cloud Resource Manager API 檢查權限。
  • 請確認 Google Cloud Platform 專案已啟用 BigQuery API。詳情請參閱「啟用及停用 API」一文。

  • 請確認服務帳戶已指派下列角色：

    • BigQuery 工作使用者
    • BigQuery 資料編輯器

    如要修改現有角色或建立自訂角色，請將下列權限新增至角色：

    • bigquery.datasets.create
    • bigquery.datasets.get
    • bigquery.jobs.create
    • bigquery.tables.create
    • bigquery.tables.get
    • bigquery.tables.updateData

建立資料儲存庫

資料儲存庫會定義匯出資料存放區 (Cloud Storage、BigQuery) 的連線，包括用於存取資料存放區的憑證。

關於 Edge 憑證保管箱

Edge 會使用憑證保管箱，安全地儲存用於存取匯出資料存放區的憑證。如要讓服務能夠存取 Edge 憑證金庫中的憑證，您必須定義憑證使用者。

使用 Edge UI 建立資料儲存庫時，Edge 會自動建立用於存取憑證的消費者。

測試資料儲存庫設定

建立資料儲存庫時，Edge 不會測試或驗證憑證和資料存放區設定是否有效。也就是說，您可以建立資料儲存庫，但在執行第一次資料匯出作業前，系統不會偵測到任何錯誤。

或者，您也可以先測試資料儲存庫設定，再建立資料儲存庫。由於大量資料匯出程序可能需要很長的時間才能執行，因此測試很有用。在開始下載大量資料前，請先測試憑證和資料儲存庫設定，以便快速修正設定中的任何問題。

如果測試成功，請建立資料儲存庫。如果測試失敗，請修正錯誤，然後重新測試設定。只有在測試成功後，才建立資料儲存庫。

如要啟用測試功能，您必須：

  • 請確認您的 Google Cloud Platform 專案已啟用 Cloud Resource Manager API。詳情請參閱「啟用及停用 API」。

建立資料儲存庫

如要在 UI 中建立資料儲存庫，請按照下列步驟操作：

  1. 以機構組織管理員身分登入 https://apigee.com/edge，然後選取貴機構。

    注意：您必須是 Edge 組織管理員，才能建立資料儲存庫。

  2. 在左側導覽列中依序選取「管理」>「Analytics Datastores」。系統會顯示「Analytics Datastores」頁面。

  3. 選取「+ 新增資料儲存庫」按鈕。系統會提示您選取資料儲存庫類型：

  4. 選擇匯出資料目標類型：

    • Google Cloud Storage
    • Google BigQuery

    設定頁面隨即顯示：

  5. 輸入資料儲存庫的名稱。

  6. 選取用來存取資料存放區的憑證。畫面上會顯示可用憑證的下拉式清單。

    憑證會依資料存放區類型而異。詳情請參閱「為 Cloud Storage 或 BigQuery 建立服務帳戶」。

    • 如果您已上傳憑證，請從下拉式清單中選取憑證。請務必選取適合資料存放區類型的憑證。

    • 如果要將新的憑證新增至資料儲存庫，請選取「新增」。在對話方塊中輸入：

      1. 憑證名稱。
      2. 「憑證內容」是指 為 Cloud Storage 或 BigQuery 建立服務帳戶所定義的資料存放區專屬 JSON 服務帳戶金鑰。
      3. 選取 [Create] (建立)。

  7. 輸入資料存放區類型專屬的屬性：

    • 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 資料集中，為分析資料建立的資料表名稱前置字串。 是

  8. 選取「測試連線」，確認憑證可用於存取資料存放區。

    如果測試成功，請儲存資料儲存庫。

    如果測試失敗，請修正任何問題，然後重試測試。將滑鼠游標移到 UI 中的錯誤訊息上，即可在工具提示中顯示其他資訊。

  9. 連線測試通過後，請儲存資料儲存庫。

修改資料儲存庫

如要修改資料儲存庫，請按照下列步驟操作：

  1. 以機構組織管理員身分登入 https://apigee.com/edge，然後選取貴機構。

  2. 在左側導覽列中依序選取「管理」>「Analytics Datastores」。系統會顯示「Analytics Datastores」頁面。

  3. 將滑鼠游標移至要修改的報表「修改」欄。系統會顯示「編輯」和「刪除」圖示。

  4. 編輯或刪除資料儲存庫。

  5. 如果您編輯了資料儲存庫，請選取「測試連線」，確認憑證可用於存取資料儲存庫。

    如果測試成功，您可以在資料存放區中查看資料樣本。

    如果測試失敗，請修正任何問題，然後重試測試。

  6. 連線測試通過後，請更新資料儲存庫。

匯出數據分析資料

如要匯出數據分析資料，請向 /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。接著，您就可以存取資料存放區中的分析資料。

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

以下要求會從 myorg 組織的 test 環境，匯出過去 24 小時的完整原始資料。內容會以 JSON 格式匯出至 Cloud Storage：

curl -X POST -H "Content-Type:application/json" \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }' \
  -u orgAdminEmail:password

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

範例 2：將資料匯出至 BigQuery

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

curl -X POST -H "Content-Type:application/json"  \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -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"
  }' \
  -u orgAdminEmail:password

注意：匯出的 CSV 檔案會建立具有下列前置字串的 BigQuery 資料表：

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

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

範例 3：匯出營利資料

如果在機構的環境中啟用營利功能，您可以執行兩種資料匯出作業：

  • 標準資料匯出，如前兩個範例所示。
  • 營利資料匯出功能可匯出營利相關資料。

如要執行營利資料匯出作業，請在要求酬載中指定 "dataset":"mint"。機構和環境必須支援營利功能，才能設定這個選項，否則請從酬載中省略 dataset 屬性：

  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository",
    "dataset":"mint"
  }'

關於 Export API 配額

為避免過度使用耗費高昂的資料匯出 API 呼叫，Edge 會針對 /analytics/exports API 的呼叫強制執行配額：

  • 如果組織和環境未啟用營利功能，配額如下：

    • 每個機構/環境每月 70 次呼叫。

    舉例來說，如果貴機構有兩個環境 (prod 和 test)，您每月可為每個環境發出 70 次 API 呼叫。

  • 對於已啟用營利功能的機構和環境，配額如下：

    • 每個機構和環境每月 70 次標準資料。
    • 每個機構和環境每月 70 次營利資料呼叫。

    舉例來說，如果您在 prod 機構啟用營利功能，則可針對標準資料發出 70 次 API 呼叫，針對營利資料發出額外 70 次 API 呼叫。

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

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

如要查看所有 Analytics 匯出要求的狀態，請向 /analytics/exports 發出 GET 要求。

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

curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -u email:password

以下提供回應範例，其中列出兩個匯出要求，一個已排入佇列 (已建立並排入佇列)，另一個已完成：

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To Cloud Storage",
    "description": "One-time export to Google Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My Cloud Storage data store",
    "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",
    ... 
  }
]

查看 Analytics 匯出要求的狀態

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

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

curl -X GET \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98" \
-u email:password

以下提供回應範例：

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

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

匯出要求資源參照

下表說明匯出數據分析資料時，您可以以 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",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }