從 Analytics (分析) 匯出資料

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

為指派的服務代理設定權限

如要為指派的服務代理程式設定權限，請在準備上述變更時按照下列步驟操作。

  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」窗格頂端的「Add」。
  5. 在「New principals」(新增主體) 欄位中輸入步驟 1 傳回的服務代理 value。舉例來說，步驟 1 顯示的 value 為 service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com。
  6. 按一下「+Add Another Role」按鈕，然後新增下列角色：
    • BigQuery 使用者
    • Storage 管理員
  7. 點按「儲存」。

Apigee 數據分析資料

Apigee Analytics 會收集並分析橫跨您 API 的多種資料，並提供視覺化工具，例如互動式資訊主頁、自訂報表，以及其他可識別 API Proxy 效能趨勢的工具。現在，您只要將 Apigee 數據分析的分析資料匯出至自己的資料存放區 (例如 Google Cloud Storage 或 Google BigQuery)，就能解鎖這些豐富內容。接著，您可以運用 Google BigQuery 和 TensorFlow 提供的強大查詢和機器學習功能，執行自己的資料分析作業。您還可以將匯出的數據分析資料與其他資料 (例如網頁記錄) 結合，藉此取得使用者、API 和應用程式的最新深入分析結果。

匯出資料格式

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

  • 逗號分隔值檔案 (CSV)

    預設分隔符號是半形逗號 (,) 字元。支援的分隔符號包括半形逗號 (,)、直立線 (|) 和定位點 (\t)。按照匯出要求屬性參考資料的說明，使用 csvDelimiter 屬性設定值。

  • JSON (以換行符號分隔)

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

匯出的資料包含 Edge 內建的所有數據分析指標和維度，以及您新增的任何自訂分析資料。如需匯出資料的說明，請參閱 Analytics (分析) 指標、維度和篩選器參考資料。

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

匯出程序總覽

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

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

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

    建立資料儲存庫時，請將資料存放區憑證上傳至 Edge Credentials Vault，安全地儲存這些憑證。然後，資料匯出機制會使用這些憑證將資料寫入資料存放區。

  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 會透過 BigQuery 匯出功能，在將資料匯出至 Cloud Storage 及 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 Credentials Vault

Edge 會使用憑證保管箱來安全地儲存用於存取匯出資料存放區的憑證。您必須定義憑證「消費者」，才能存取 Edge Credentials Vault 中的憑證。

如下方所述，使用 Edge UI 建立資料儲存庫時，Edge 會自動建立用來存取憑證的消費端。

測試資料儲存庫設定

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

或者，您也可以在建立資料儲存庫設定前先測試該設定。測試非常有用，因為執行大型資料匯出程序可能需要很長的時間才能完成。只要在開始下載大量資料前測試憑證和資料儲存庫設定，即可快速修正設定中的所有問題。

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

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

  • 確認您的 Google Cloud Platform 專案已啟用 Cloud Resource Manager API。如需操作說明，請參閱啟用及停用 API。

建立資料儲存庫

如要在 UI 中建立資料儲存庫：

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

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

  2. 在左側導覽列中，依序選取「管理」>「Analytics Datastore」。接著，「Analytics Datastores」頁面就會出現。

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

  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 說明文件中的建立及管理專案。

      		是
      值區名稱 要匯出數據分析資料的 Cloud Storage 值區名稱。執行資料匯出作業前，值區必須存在。

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

      		是
      路徑 要在 Cloud Storage 值區中儲存分析資料的目錄。 是
    • 針對 BigQuery：
      屬性 說明 必填與否
      專案 ID Google Cloud Platform 專案 ID。

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

      		 是
      資料集名稱 指定要匯出數據分析資料的 BigQuery 資料集名稱。請務必先建立資料集，再要求匯出資料。

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

      		 是
      資料表前置字串 為 BigQuery 資料集建立數據分析資料的資料表名稱，這些資料表名稱的前置字串。 是

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

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

    如果測試失敗，請修正問題並重新測試。只要將遊標移到使用者介面中的錯誤訊息上，就能在工具提示中顯示其他資訊。

  9. 通過連線測試後，即可「儲存」資料儲存庫。

修改資料儲存庫

如要修改資料儲存庫：

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

  2. 在左側導覽列中，依序選取「管理」>「Analytics Datastore」。接著，「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 屬性中傳回的網址查看資料匯出要求的狀態，如「查看 Analytics (分析) 匯出要求的狀態」一節所述。要求完成後，回應中的 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 監控工作狀態，如「查看數據分析匯出要求的狀態」一文所述。

範例 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 會傳回 HTTP 429 回應。

查看所有數據分析匯出要求的狀態

如要查看所有數據分析匯出要求的狀態，請向 /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/exports/{exportId} 發出 GET 要求，其中 {exportId} 是與數據分析匯出要求相關聯的 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"
}

如果數據分析匯出項目未傳回任何數據分析資料，則 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

如果將 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"
  }