從 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 使用者
    • 儲存空間管理員
  7. 按一下 [儲存]。

Apigee Analytics 資料

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

匯出資料格式

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

  • 逗號分隔值 (CSV)

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

  • JSON (以換行符號分隔)

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

匯出的資料包括 Edge 內建的所有 Analytics 指標和維度，以及您新增的任何自訂 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 bucket 的寫入權限。如要建立服務金鑰並下載必要酬載，請參閱 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 會使用 BigQuery API，在匯出至 Cloud Storage 時運用 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，然後選取機構。

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

  2. 從左側導覽列選取「管理」>「Analytics 資料儲存庫」。系統隨即會顯示「Analytics Datastores」(Analytics 資料儲存區) 頁面。

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

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

    • Google Cloud Storage
    • Google BigQuery

    隨即會顯示設定頁面：

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

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

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

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

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

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

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

    • Google Cloud Storage：
      屬性 說明 是否必要？
      專案 ID Google Cloud Platform 專案 ID。

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

      		是
      Bucket Name 要將數據分析資料匯出至哪個 Cloud Storage bucket 的名稱。執行資料匯出作業前，bucket 必須已存在。

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

      		是
      路徑 在 Cloud Storage bucket 中儲存 Analytics 資料的目錄。 是
    • BigQuery：
      屬性 說明 是否必要？
      專案 ID Google Cloud Platform 專案 ID。

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

      		 是
      資料集名稱 要匯出 Analytics 資料的 BigQuery 資料集名稱。請務必先建立資料集，再要求匯出資料。

      如要建立 BigQuery 資料集，請參閱 Google Cloud Platform 說明文件中的「建立及使用資料集」。

      		 是
      資料表前置字串 在 BigQuery 資料集中為 Analytics 資料建立的資料表名稱前置字串。 是

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

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

    如果測試失敗，請修正問題並重試。將滑鼠游標移到使用者介面中的錯誤訊息上方，即可在工具提示中查看額外資訊。

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

修改資料儲存庫

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

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

  2. 從左側導覽列選取「管理」>「Analytics 資料儲存庫」。系統隨即會顯示「Analytics Datastores」(Analytics 資料儲存區) 頁面。

  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

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

範例 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"
  }'

匯出 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 的 Analytics 匯出要求狀態。

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"
}

如果分析資料匯出作業未傳回任何分析資料，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，結束時間為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",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }