Analytics からデータをエクスポートする

Apigee Analytics は、API を介して送受信されるさまざまなデータを収集して、分析します。Apigee Analytics では、インタラクティブなダッシュボードやカスタム レポート、API プロキシ パフォーマンスの傾向を識別するツールなどの可視化ツールを利用できます。

Apigee Analytics による豊富なコンテンツを自由に利用できるようにするために、この Analytics データを Google Cloud Storage や BigQuery などの独自のデータ リポジトリにエクスポートできるようになりました。これにより、Google Cloud BigQuery と TensorFlow が提供する強力なクエリと機械学習の機能を活用し、独自のデータ分析を行うことができます。また、Analytics からエクスポートしたデータにウェブログなどの他のデータを結合すれば、ユーザー、API、アプリケーションについて新しい分析情報を入手することも可能になります。

データのエクスポート形式

Analytics データは、次のいずれかの形式にエクスポートできます。

• カンマ区切り値（CSV）

  デフォルトの区切り文字はカンマ（,）です。サポートされている区切り文字には、カンマ（,）、パイプ（|）、タブ（\t）があります。区切り文字の値を構成するには、エクスポート リクエスト プロパティのリファレンスで説明されているように csvDelimiter プロパティを使用します。

• JSON（改行区切り）

  改行文字を区切り文字として使用できます。

エクスポートされるデータには、Edge に組み込まれているアナリティクス指標とディメンションのすべてが含まれます。また、カスタム アナリティクス データを追加している場合は、そのデータも含まれます。エクスポートされるデータについては、アナリティクス指標、ディメンション、フィルタのリファレンスをご覧ください。

Analytics データは、次のデータ リポジトリにエクスポートできます。

• Google Cloud Storage（GCS）
• Google BigQuery

エクスポート プロセスの概要

次の手順は、Analytics データをエクスポートする際に従うプロセスを要約したものです。

1. データのエクスポート先とするデータ リポジトリを構成します（GCS または BigQuery）。データ リポジトリが正しく構成されていることを確認する必要があります。また、データ リポジトリへのデータの書き込みに使用するサービス アカウントに適切な権限が付与されていることも確認してください。

2. データのエクスポート先データ リポジトリ（GCS または BigQuery）のプロパティを定義するデータストアを作成します。これらのプロパティには、データ リポジトリにアクセスするために使用する認証情報も含まれます。

   データストアの作成時に、データ リポジトリの認証情報を安全に保管するために、認証情報を Edge 認証情報コンテナにアップロードします。データ エクスポート メカニズムではデータをデータ リポジトリに書き込む際に、これらの認証情報を使用します。

3. Data Export API を使用して、データ エクスポートを開始します。データ エクスポートはバックグラウンドで非同期的に実行されます。

4. Data Export API を使用して、エクスポートが完了したかどうかを判別します。

5. エクスポートが完了したら、データ リポジトリでエクスポートされたデータにアクセスします。

以降のセクションで、上記の 3 つのステップについて詳しく説明します。

データ リポジトリを構成する

Analytics のデータ エクスポート メカニズムは、データを GCS または BigQuery に書き込みます。この書き込みが行われるようにするには、次の作業を行う必要があります。

• Google Cloud Platform サービス アカウントを作成します。
• サービス アカウントが GCS または BigQuery にアクセスできるように、サービス アカウントの役割を設定します。

GCS または BigQuery 用のサービス アカウントを作成する

サービス アカウントとは、個々のユーザーではなくアプリケーションに属するタイプの Google アカウントのことです。アプリケーションはサービス アカウントを使用してサービスにアクセスできます。

サービス アカウントには、JSON 文字列で表された「サービス アカウント キー」が割り当てられます。データ リポジトリとの接続を定義する Edge データストアを作成するときは、このキーを 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 API が有効にされていること。手順については、API の有効化と無効化をご覧ください。Apigee は BigQuery のエクスポート機能を使用するため、GCS へのエクスポートには BigQuery API が必要です。

• サービス アカウントに次の役割が割り当てられていること。

  • BigQuery ジョブユーザー
  • ストレージ オブジェクト作成者
  • ストレージ管理者（データストアの構成をテストするの手順に従ってデータストアをテストする場合にのみ必要）。このロールでは権限の範囲が広すぎる場合、既存のロールに storage.buckets.get 権限を追加することもできます）。

  既存のロールに変更を加える場合、またはカスタムロールを作成する場合は、そのロールに次の権限を追加します。

  • bigquery.jobs.create
  • storage.objects.create
  • storage.buckets.get（データストアの構成をテストするの手順に従ってデータストアをテストする場合にのみ必要）

Google BigQuery を構成する

Google BigQuery にデータをエクスポートするには、次の要件を満たしている必要があります。

• Google Cloud Platform プロジェクトで BigQuery が有効にされていること。
• 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

データストアを作成する

データストアは、データ リポジトリにアクセスするために使用する認証情報を含め、エクスポート データ リポジトリ（GCS または BigQuery）との接続を定義します。

Edge 認証情報コンテナについて

Edge ではエクスポート データ リポジトリにアクセスするために使用する認証情報を安全に保管するために、認証情報コンテナを使用します。サービスから Edge 認証情報コンテナ内の認証情報にアクセスできるようにするには、認証情報の「コンシューマ」を定義する必要があります。

下記の説明に従って Edge UI を使用してデータストアを作成すると、資格情報にアクセスするために使用するコンシューマが Edge によって自動的に作成されます。

データストアの構成をテストする

ユーザーがデータストアを作成する際、Edge は認証情報とデータ リポジトリの構成が有効であることのテストも検証も行いません。つまり、データストアを作成し、最初のデータのエクスポートを実行するまでは、エラーは検出されません。

代わりの手段として、データストアを作成する前に、その構成をテストできます。このテストが有用なのは、大量のデータのエクスポート プロセスの実行には時間がかかるためです。大量のデータのダウンロードを開始する前に認証情報とデータストアの構成をテストすれば、設定に問題がある場合はそれを見つけてすばやく修正できます。

テストが成功したら、データストアを作成します。テストが失敗した場合は、エラーを修正してから構成を再テストします。テストが成功した場合にのみ、データストアを作成します。

テスト機能を有効にするには、次の要件を満たす必要があります。

• Google Cloud Platform プロジェクトで Cloud Resource Manager API が有効にされていること。手順については、API の有効化と無効化をご覧ください。

データストアを作成する

UI でデータストアを作成するには:

1. 組織管理者として https://apigee.com/edge にログインし、自分の組織を選択します。

   注: データストアを作成するには、Edge 組織管理者である必要があります。

2. 左側のナビゲーション バーから [Admin] > [Analytics Datastores] を選択します。[Analytics Datastores] ページが表示されます。

3. [+ Add Datastore] ボタンを選択します。データストアのタイプを選択するよう求められます。

   

4. エクスポート データのターゲットのタイプを選択します。

   • Google Cloud Storage
   • Google BigQuery

   構成ページが表示されます。

   

5. [Name] に、データストアの名前を入力します。

6. [Select a credential] で、データ リポジトリにアクセスするために使用する認証情報を選択します。プルダウン リストに使用可能な認証情報が示されます。

   認証情報は、データ リポジトリのタイプに固有です。詳しくは、GCS または BigQuery 用のサービス アカウントを作成するをご覧ください。

   • すでに認証情報をアップロードした場合、プルダウン リストからその認証情報を選択します。必ず、データ リポジトリのタイプに適した認証情報を選択してください。

   • データストアに新しい認証情報を追加する場合、[Add new] を選択します。ダイアログ ボックスで、次の情報を入力します。

     1. [Credentials name] に、認証情報の名前を入力します。
     2. [Credentials content] には認証情報の内容として、GCS または BigQuery 用のサービス アカウントを作成するで定義した、データ リポジトリに固有の JSON サービス アカウント キーを入力します。
     3. [Create] を選択します。

7. データ リポジトリのタイプに固有のプロパティを入力します。

   • Google Cloud Storage の場合:

     プロパティ	説明	必須
     Project ID	Google Cloud Platform プロジェクト ID。 Google Cloud Platform プロジェクトを作成するには、Google Cloud Platform ドキュメントのプロジェクトの作成と管理をご覧ください。	○
     Bucket Name	Analytics データのエクスポート先とする、Google Cloud Storage 内のバケットの名前。このバケットは、データ エクスポートを実行する前に存在している必要があります。 Google Cloud Storage バケットを作成するには、Google Cloud Platform ドキュメントのストレージ バケットの作成をご覧ください。	○
     Path	Analytics データの保存先とする、Google Cloud Storage バケット内のディレクトリ。	○

   • BigQuery の場合:

     プロパティ	説明	必須
     Project ID	Google Cloud Platform プロジェクト ID。 Google Cloud Platform プロジェクトを作成するには、Google Cloud Platform ドキュメントのプロジェクトの作成と管理をご覧ください。	○
     Dataset Name	Analytics データのエクスポート先とする BigQuery データセットの名前。データ エクスポートをリクエストする前に、このデータセットが作成されていることを確認してください。 BigQuery データセットを作成するには、Google Cloud Platform ドキュメントのデータセットの作成と使用をご覧ください。	○
     Table Prefix	Google BigQuery データセット内に Analytics データ用に作成されるテーブルの名前の接頭辞。	○

8. 認証情報を使用してデータ リポジトリにアクセスできることを確認するために、[Test connection] を選択して接続をテストします。

   テストが成功した場合、データストアを保存します。

   テストが失敗した場合、問題を修正してからテストを再試行します。UI に表示されるエラー メッセージにマウスポインタを重ねると、ツールチップに詳細情報が表示されます。

9. 接続テストに合格したら、[Save] を選択してデータストアを保存します。

データストアを変更する

データストアを変更するには:

1. 組織管理者として https://apigee.com/edge にログインし、自分の組織を選択します。

2. 左側のナビゲーション バーから [Admin] > [Analytics Datastores] を選択します。[Analytics Datastores] ページが表示されます。

3. 変更を加えるには、レポートの [Modified] 列にマウスポインタを重ねます。編集アイコンと削除アイコンが表示されます。

4. データストアを編集または削除します。

5. データストアを編集した場合、認証情報を使用してデータストアにアクセスできることを確認するために、[Test connection] を選択して接続をテストします。

   テストが成功した場合、データ リポジトリ内のサンプルデータを表示できます。

   テストが失敗した場合、問題を修正してテストを再試行します。

6. 接続テストに合格したら、[Update] を選択してデータストアを更新します。

Analytics データをエクスポートする

Analytics データをエクスポートするには、/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 リクエストは非同期的に機能します。つまり、POST リクエストはレスポンスを返した後も、引き続きバックグラウンドで実行されます。state に有効な値は、enqueued、running、completed、failed です。

self プロパティで返される URL を使用して、データ エクスポート リクエストのステータスを確認します。手順については、特定の Analytics エクスポート リクエストのステータスを表示するをご覧ください。リクエストが完了すると、レスポンスに含まれる state プロパティの値が completed に設定されます。これで、データ リポジトリ内の Analytics データにアクセスできるようになります。

例 1: Google Cloud Storage にデータをエクスポートする

次のリクエストにより、myorg 組織の test 環境から、過去 24 時間にわたる元データ一式がすべてエクスポートされます。データセットの内容は JSON 形式で Google 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 GCS",
    "description": "Export raw results to GCS for last 24 hours",
    "dateRange": {
      "start": "2018-06-08",
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My gcs data repository"
  }' \
  -u orgAdminEmail:password

self プロパティで指定されている URI を使用して、ジョブ ステータスをモニタリングします。手順については、特定の Analytics エクスポート リクエストのステータスを表示するをご覧ください。

例 2: Big Query にデータをエクスポートする

次のリクエストにより、カンマ区切り CSV ファイルが Big Query にエクスポートされます。

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 Big Query",
    "description": "One-time export to Big Query",
    "dateRange": {
      "start": "2018-06-08",
      "end": "2018-06-09"
    },
    "outputFormat": "csv",
    "csvDelimiter": ",",
    "datastoreName": "My bq data repository"
  }' \
  -u orgAdminEmail:password

self プロパティで指定されている URI を使用して、ジョブ ステータスをモニタリングします。手順については、特定の Analytics エクスポート リクエストのステータスを表示するをご覧ください。

例 3: 収益化データをエクスポートする

組織の環境で収益化が有効にされている場合、次の 2 つのタイプのデータ エクスポートを行うことができます。

• 上記の 2 つの例と同じ標準的なデータ エクスポート。
• 収益化に固有のデータをエクスポートする収益化データ エクスポート。

収益化データ エクスポートを行うには、リクエスト ペイロードで "dataset":"mint" を指定します。このオプションを設定するには、組織と環境が収益化をサポートしている必要があります。サポートされていない場合、ペイロードで dataset プロパティを省略してください。

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

Export API の割り当てについて

コストのかかる Data Export API 呼び出しの過剰な使用を防ぐために、Edge では /analytics/exports API の呼び出しに割り当てを適用しています。

• 収益化が有効にされていない組織と環境での割り当ては次のとおりです。

  • 組織 / 環境ごとに 1 か月あたり 70 回の呼び出し。

  たとえば、組織に 2 つの環境（prod と test）がある場合、環境ごとに 1 か月あたり 70 回の API 呼び出しが許可されます。

• 収益化が有効にされている組織と環境での割り当ては次のとおりです。

  • 標準データの場合、組織 / 環境ごとに 1 か月あたり 70 回の呼び出し。
  • 収益化データの場合、組織 / 環境ごとに 1 か月あたり 70 回の呼び出し。

  たとえば、prod 組織で収益化が有効にされている場合、標準データについて 70 回の API 呼び出しが許可され、さらに収益化データについて 70 回の API 呼び出しが許可されます。

呼び出しの割り当てを超えた場合、API は HTTP 429 レスポンスを返します。

すべての Analytics エクスポート リクエストのステータスを表示する

すべての Analytics エクスポート リクエストのステータスを表示するには、GET リクエストを /analytics/exports に送信します。

たとえば、次のリクエストにより、myorg 組織の test 環境で行われたすべての Analytics エクスポート リクエストのステータスが返されます。

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

次の例は、2 つのエクスポート リクエスト、つまりキュー内の（作成されてキューに入っている）ものと、完了したものをリストするレスポンスを示しています。

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To GCS",
    "description": "One-time export to Google Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My gcs 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 エクスポート リクエストのステータスを表示するには、GET リクエストを /analytics/exports/{exportId} に送信します。ここで、{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 GCS",
  "description": "One-time export to Google Cloud Storage",
  "userId": "my@email.com",
  "datastoreName": "My gcs data store",
  "executionTime": "36 seconds",
  "created": "2018-09-28T12:39:35Z",
  "updated": "2018-09-28T12:39:42Z",
  "state": "enqueued"
}

Analytics エクスポートで Analytics データが返されなかった場合、executionTime は「0 秒」に設定されます。

エクスポート リクエスト プロパティのリファレンス

次の表で、Analytics データをエクスポートするときに、JSON 形式のリクエスト本文で渡すことができるプロパティについて説明します。

"dateRange": {
    "start": "2018-07-29",
    "end": "2018-07-30"
}

例:

{
  "name": "Export raw results to GCS",
  "description": "Export raw results to Google Cloud Storage for last 24 hours",
  "datastoreName": "My gcs data store"
}