ログ レベル データ - クラウドエクスポート

クラウド エクスポートは、Log-Level データ (LLD) をクラウド ストレージに自動的に転送するために使用される機能です。 Xandr では、Amazon S3 バケット、Google Cloud Storage バケット、Microsoft Azure Blob Storage コンテナーへのデータ転送がサポートされています。 バッチ データが使用可能になるとすぐに、データの転送が開始されます。 この設定により、Xandr クライアントの有効化が高速化され、より簡単なワークフローが提供されます (たとえば、Log-Level Data サービスと同様にサイホン サービスをポーリングする必要はありません)。

クラウド エクスポートのセットアップ

前提条件

セットアップに進む前に、次の内容を確認してください。

1. 使用する予定の LLD フィードは、Xandr シート (メンバー ID) に対して既に有効になっている必要があります。 そうでない場合は、アカウント担当者に問い合わせてログ レベルのデータをサブスクライブしてください。
2. 現時点では、Xandr Cloud Export では、 protobuf 形式、 protobuf 区切り形式、 および avro 形式のみがサポートされています。
3. 以下の手順を実行するには、ネットワーク 管理特権が必要です。

セットアップ

エクスポート先のクラウド ベンダーについては、以下のセクションの手順に従ってください。 Xandr は現在、Xandr UI を使用して次をサポートしています。

• Amazon S3
• Microsoft Azure Blob Storage
• Google Cloud Storage

Amazon S3

1. Xandr Cloud Export システムからのログレベルのデータのドロップ ボックスとして機能する Amazon S3 バケット を作成します。

2. Microsoft Invest または Microsoft 収益化 UI のネットワーク (またはレポート) メニューから [ログ レベル データ] を選択します。

3. S3 エクスポートを作成するフィードの [クラウド エクスポート] 列で [管理] をクリックします。 Amazon S3 セクションが表示されます。

4. [ 新規 ] をクリックして新しいエクスポートを設定するか 、[構成] をクリック して既存のエクスポートを編集します。 [ Cloud Export to: Amazon S3 ] ページが表示されます。

5. セットアップ。 次の表に情報を入力し、[ 保存] をクリックします。

   設定	説明
   バケット	手順 1 で作成した Amazon S3 バケット の名前。
   マニフェスト パス	マニフェスト ファイルのルート ( /manifests など)。 このファイル パスはマクロをサポートしていません。
   フィード パス	マクロを含むフィード パス (例: /feed/%FEED_NAME%/%YEAR%/%MONTH%/%DAY%/%HOUR%/%TIMESTAMP%)
   通知Email	メールのコンマ区切りリスト。 Cloud Export がバケットにアクセスできなくなった場合、エクスポートは非アクティブ化され、電子メールで通知されます。
   Format	ログ レベルのデータ ファイルのデータ形式 ( 例: protobuf )
   サーバー側の暗号化	アップロードされた LLD ファイルに適用されるサーバー側の暗号化: - なし - サーバー側の暗号化を適用しない - SSE-S3 - Amazon S3 で管理される暗号化キーを使用してサーバー側の暗号化を適用する - SSE-KMS - AWS KMS で管理される暗号化キーを使用してサーバー側の暗号化を適用します。 Xandr AWS ユーザーに キーへのアクセス権を付与する必要があります。 SSE-S3 または SSE-KMS を選択すると、アップロードされたファイルの 既定のバケット暗号化設定 がオーバーライドされます。

1. 承認。 Xandr メンバーシートごとに、Xandr は S3 バケットにデータをアップロードする一意の AWS ユーザーを作成します。 Xandr は、AWS ユーザーが バケット にアクセスできるようにするバケットに 適用 する推奨バケット ポリシーを生成します。 このポリシーをそのまま使用できますが、既にバケットにポリシーが適用されている場合は、ポリシー ステートメントを自分のポリシー ステートメントとマージする必要があります。

2. 検証。 バケットにポリシーを適用したら、S3 Cloud Export をアクティブ化する前にアクセス許可を確認する必要があります。 実際のエクスポート中に発生するアクションを模倣する一連のテストを実行するには、[ 確認 ] ( [Cloud Export to: Amazon S3 ] ページで) をクリックします。 エクスポートが確認されると、アクティブになります。 フィードからのデータは自動的に S3 バケットにエクスポートされます (次の 1 時間後から)。

Microsoft Azure Blob Storage

1. 1 つ以上のストレージ コンテナーをホストする Azure ストレージ アカウント を作成します。

2. ストレージ アカウント内に Azure Blob Storage コンテナー を作成します。これは、Xandr Cloud Export システムからのログ レベルのデータのドロップ ボックスとして機能します。

3. Xandr UI のネットワーク (またはレポート) メニューから [ログ レベル データ] を選択します。

4. Azure Blob Storage エクスポートを作成するフィードの [クラウド エクスポート] 列で [管理] をクリックします。 [Microsoft Azure Blob Storage] セクションが表示されます。

5. [ 新規 ] をクリックして新しいエクスポートを設定するか 、[構成] をクリック して既存のエクスポートを編集します。 [Cloud Export to: Microsoft Azure Blob Storage] ページが表示されます。

6. セットアップ。 次の表に情報を入力し、[ 保存] をクリックします。

   設定	説明
   ストレージ アカウント	手順 1 で作成した Azure ストレージ アカウント の名前。
   Container	手順 2 で作成した Azure Blob Storage コンテナー の名前。
   マニフェスト パス	マニフェスト ファイルのルート ( /manifests など)。 このファイル パスはマクロをサポートしていません。
   フィード パス	マクロを含むフィード パス (例: /feed/%FEED_NAME%/%YEAR%/%MONTH%/%DAY%/%HOUR%/%TIMESTAMP%)
   通知Email	メールのコンマ区切りリスト。 Cloud Export がコンテナーにアクセスできなくなった場合、エクスポートは非アクティブ化され、電子メールで通知されます。
   Format	ログ レベルのデータ ファイルのデータ形式 ( 例: protobuf)

7. 承認。 次のアクセス許可を持つストレージ アカウントの 共有アクセス署名 (SAS) を生成します。

   • 許可されるサービス - BLOB
   • 許可されるリソースの種類 - コンテナー、 オブジェクト
   • 許可されるアクセス許可 - 読み取り、 書き込み、 削除、 一覧表示、 追加、 作成
   • 開始日と有効期限の日付/時刻 - 遠い将来の有効期限を選択します
   • 許可されるプロトコル - HTTPS のみ
   • SAS トークンを作成したら、Xandr UI の SAS トークン フィールドに貼り付けて、[ 保存] をクリックします。

8. 検証。 SAS トークンを付与したら、Azure Blob Storage Cloud Export をアクティブ化する前に SAS アクセス許可を確認する必要があります。 実際のエクスポート中に発生するアクションを模倣する一連のテストを実行するには、[確認] ([Cloud Export to: Microsoft Azure Blob Storage] ページ) をクリックします。 エクスポートが確認されると、アクティブになります。 フィードからのデータは、(次の 1 時間後から) Azure コンテナーに自動的にエクスポートされます。

Google Cloud Storage

1. Xandr Cloud Export システムからのログ レベルのデータのドロップ ボックスとして機能する Google Storage バケット を作成します。

2. Xandr UI のネットワーク (またはレポート) メニューから [ログ レベル データ] を選択します。

3. Google Cloud Storage エクスポートを作成するフィードの [クラウド エクスポート] 列で [管理] をクリックします。 [Google Cloud Storage] セクションが表示されます。

4. [ 新規 ] をクリックして新しいエクスポートを設定するか 、[構成] をクリック して既存のエクスポートを編集します。 [ Cloud Export to: Google Cloud Storage ] ページが表示されます。

5. 承認。 Cloud Storage コンソールに移動し、バケットを選択し、[情報パネルの表示] をクリックします。 バケットのアクセス許可に Google メンバー prod-lld-gcs-{XANDR MEMBER ID}@appnexus-cloud-export.iam.gserviceaccount.com を追加し、 Cloud Storage IAM ロール を割り当てます (このロールには完全な管理者アクセス権があります)。 Xandr メンバー ID 123456の Google メンバーの例を次に示します。 prod-lld-gcs-123456@appnexus-cloud-export.iam.gserviceaccount.com

6. セットアップ。 次の表に情報を入力し、[ 保存] をクリックします。

   設定	説明
   バケット	手順 1 で作成した Google Storage バケット の名前。
   マニフェスト パス	マニフェスト ファイルのルート ( /manifests など)。 このファイル パスはマクロをサポートしていません。
   フィード パス	マクロを含むフィード パス (例: /feed/%FEED_NAME%/%YEAR%/%MONTH%/%DAY%/%HOUR%/%TIMESTAMP%)
   通知Email	メールのコンマ区切りリスト。 Cloud Export がバケットにアクセスできなくなった場合、エクスポートは非アクティブ化され、電子メールで通知されます。
   フォーマット	ログ レベルのデータ ファイルのデータ形式 ( 例: protobuf)

   警告

   マニフェストまたはフィード関連のパスは手動で作成しないでください。 これにより、オブジェクト レベルの ACL が原因でエクスポートが検証に失敗します。

   必要なパスは Xandr によって自動的に作成されます。

7. 検証。 Google メンバーにバケット内のストレージ 管理 ロールを付与したら、Google Storage Cloud Export をアクティブ化する前にアクセス許可を確認する必要があります。 実際のエクスポート中に発生するアクションを模倣する一連のテストを実行するには、[ 確認 ] ([ Cloud Export to: Google Cloud Storage ] ページで) をクリックします。 エクスポートが確認されると、アクティブになります。 フィードからのデータは自動的に Google Cloud Storage バケットにエクスポートされます (次の 1 時間後から)。

エラーとエクスポートの非アクティブ化

エクスポートが失敗した場合、Xandr は検証テストを自動的に実行して、エラーがアクセス許可の問題によって発生しなかったことを確認します。

• アクセス許可の問題が原因でエラーが発生した場合、エクスポートは非アクティブ化され、電子メールで通知されます。 その後、エクスポートを再検証する必要があります。 検証が成功すると、エクスポートが再アクティブ化されます。
• アクセス許可の問題が原因でエラーが発生しなかった場合、エクスポートは自動的に再実行されます。

フィード パス マクロ

マクロは、フィード パス内で使用して、データ時間、フィード タイムスタンプ、およびその他のメタデータによってフィード出力の場所をカスタマイズできます。 サポートされているマクロを次に示します。

マニフェスト ファイル

マニフェスト ファイルは、Cloud Export サービスによってアップロードされたファイルを追跡するのに役立ちます。 クラウド オブジェクト ストア (Amazon S3、Azure Blob Storage、Google Cloud Storage など) は最終的に一貫性があるため、ダウンストリームのコンシューマーには真実のソース (つまり、どのファイルが存在する必要があるか) が必要です。 マニフェスト ファイルは、バケット内の事前に構成された場所に書き込まれた JSON オブジェクトです。 これは JSONSchema 形式で指定されます。 パスのすべてのアクセス (たとえば、データ処理、消去など) は、最初にマニフェスト ファイルを参照して行うことをお勧めします。 マニフェスト ファイルには、データの年齢、状態、および形式に関する重要な情報が含まれています。

ファイルの名前付けとパス

マニフェスト ファイルは、フィードが特定の時間の処理を開始するときに作成されます。 ファイルは、指定したパスの場所に作成されます。 マニフェスト ファイル名には、フィードの名前、データの時間 (カバーする時間の範囲) を示すタイムスタンプ、および処理タイムスタンプが含まれます。 フィード、メンバー (シート) ID、データの時間、フィードの実行ごとにマニフェスト ファイルが作成されます。 Xandr は、必要に応じてデータを自動的に再処理します。 ファイルには、関連付けられているフィード ジョブの状態を示すサフィックスも付けられます。

• マニフェスト ファイルのサフィックスが "-failed" または "-processing" の場合は、フィードが正常に処理されなかったことを示します。
• マニフェスト ファイルにサフィックスがない場合は、フィードのデータを取り込む準備ができていることを示します。

一般的な形式

{feed_name}-{seat_id}-{YYYYMMddHH}-{yyyyMMddHHmmss}.json[-{suffix}]

状態: "処理"

状態: "Failed"

状態: "成功"

フィード処理ワークフロー

フィード ジョブがマニフェスト ファイルを解釈してダウンストリーム ロジックを構築する方法を理解すると便利です。 このプロセスは次のとおりです。

1. マニフェスト パスは、"処理" サフィックスを持つエントリをスキャンします。 このサフィックスを持つエントリは、致命的なエラーが発生した以前の実行を示します。 これらのエントリの名前は、"失敗" サフィックス ( json-processing>.json-failed など) で変更されます。  
2. マニフェスト ファイルが生成され、"処理" サフィックスが付いたバケットに書き込まれます。
3. フィード データはバケットに書き込まれます。
4. 書き込みプロセスが失敗した場合、マニフェスト ファイルの名前が変更され、"失敗" サフィックス ( .json失敗など) が含まれます。 書き込みプロセスが正常に完了した場合、"処理" サフィックスは単純に削除されます (例: .json処理>.json)。完了した実行を示します。

マニフェスト ファイル スキーマ

マニフェスト ファイルのスキーマは、よく知られている JSONSchema 形式で記述されています。 Xandr は、提供する JSONSchema からコード生成クラスを推奨します。 Java でこれを実現するプロジェクトは jsonschema2pojo です。  

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Schema for the cloud export feed file manifest",
  "type": "object",
  "required": [
    "hour",
    "files",
    "feed_type",
    "path",
    "processed_on",
    "feed_properties",
    "seat_id"
  ],
  "properties": {
    "hour": {
      "description": "Timestamp for the data in yyyy-MM-dd HH:mm:ss",
      "type": "string"
    },
    "files": {
      "description": "array of object describing the exported files",
      "type": "array",
      "items": {
        "$ref": "#/definitions/feed_file"
      }
    },
    "feed_type": {
      "description": "name of the feed",
      "type": "string"
    },
    "path": {
      "description": "fully qualified destination location",
      "type": "string"
    },
    "processed_on": {
      "description": "completion timestamp of feed (yyyyMMddHHmmss)",
      "type": "string"
    },
    "feed_properties": {
      "description": "data format related information",
      "type": "object",
      "$ref": "#/definitions/feed_properties"
    },
    "seat_id" : {
      "description" : "the Xandr seat id that these files belong to",
      "type" : "integer"
    }
  },
  "definitions": {
    "feed_file": {
      "type": "object",
      "required": [
        "checksum",
        "name"
      ],
      "properties": {
        "checksum": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "feed_properties": {
      "type": "object",
      "required": [
        "compression_type",
        "container_format",
        "checksum_type",
        "data_format"
      ],
      "properties": {
        "compression_type": {
          "description": "type of compression used on the files (BLOCK level compression for sequence files)",
          "type": "string",
          "enum": [
            "DEFLATE",
            "GZIP",
            "SNAPPY",
            "NONE"
          ]
        },
        "container_format": {
          "description": "container format of the data",
          "type": "string",
          "enum": [
            "AVRO",
            "SEQUENCE",
            "NONE"
          ]
        },
        "data_format": {
          "description": "format of the data",
          "type": "string",
          "enum": [
            "protobuf",
            "protobuf-delimited",
            "avro"
          ]
        },
        "checksum_type": {
          "description": "type of checksum",
          "type": "string",
          "enum": [
            "MD5"
          ]
        }
      }
    }
  }
}

マニフェスト ファイルの例

{
  "hour" : "2017-02-09 16:00:00",
  "files" : [ {
    "checksum" : "ccd5774e8fc785b4df3d63627f992c4b",
    "name" : "998-10-ccd5774e8fc785b4df3d63627f992c4b-998"
  }, {
    "checksum" : "c8c442ff5eb24237573faa2d60a689b1",
    "name" : "998-11-c8c442ff5eb24237573faa2d60a689b1-998"
  } ],
  "feed_type" : "standard_feed",
  "path" : "/standard_feed/2017/02/09/16/20170209220747",
  "processed_on" : "20170209220747",
  "feed_properties" : {
    "compression_type" : "SNAPPY",
    "container_format" : "SEQUENCE",
    "data_format" : "protobuf",
    "checksum_type" : "MD5"
  },
  "seat_id" : 998
}

エラー/部分読み込み

フィード ジョブの失敗により、部分的なデータ読み込みが発生する可能性があります。 部分的に読み込まれたデータを使用しないようにするには、マニフェスト ファイル名を使用して、使用する内容を決定します。

• "-processing" または "-failed" のサフィックスを持つファイルは使用しないでください。 これらは不完全なデータ セットです。
• 完了した読み込み (つまり、 .json 拡張子を持つマニフェスト ファイルが追加のサフィックスを持たない) に対応するパスからのデータのみを使用します。

パージ

バケットから古いデータを消去する場合は、データが消去の対象となるタイミングを判断するためにマニフェスト ファイルを使用する必要があります。 関連しなくなったファイル (たとえば、1 週間以上前) のみを消去します。

再

特定の時間に再処理されたフィードは、古いデータを上書きすることはありません。 不整合が検出されると、Xandr によってデータが再処理されます。 フィード ジョブが再処理されると、同じデータ時間に対応する 2 つ以上のマニフェスト ファイルが存在します。 ただし、処理タイムスタンプとパスは実行によって異なります。 最新のタイムスタンプを持つファイルは、修正されたファイルになります。

クライアント データ損失

Xandr は、既に正常にエクスポートされたデータを再エクスポートしません。 誤ってエクスポートされたデータを誤って削除した可能性がある状況を軽減するには、クラウド プロバイダーのバックアップまたはバージョン管理機能を活用することをお勧めします。

トラブルシューティング

構成の一意性基準

Cloud Export 構成は一意である必要があります。つまり、次のことを意味します。

• マニフェスト パスの場合:
  • Microsoft Azure の場合、変換先 (ストレージ アカウントとコンテナー) と Path が同じ場合、メンバー ID とフィードは異なる必要があります。
  • その他のすべての構成では、バケットとパスが同じ場合、メンバー ID とフィードが異なる必要があります。
• フィード パスの場合、変換先と解決されたフィード パスが同じ場合、メンバー ID は異なる必要があり、フィードと形式は同じである必要があります。

検証の問題

以下のセクションでは、検証の設定時に発生する可能性があるいくつかの一般的な問題について説明します。

失敗した可能性のある検証アクション:

• GLACIER でマニフェスト ファイルを確認する
• マニフェスト ファイルに対するメタ情報アクセスの確認
• でプレフィックスを作成する <path>

GLACIER でマニフェスト ファイルを確認する

考えられる原因: マニフェスト ファイルのアーカイブが適切に設定されていない

適用対象: Amazon S3

解決策:

マニフェスト オブジェクトがマニフェスト パスに含まれていない場合にのみ、マニフェスト オブジェクトを Glacier に移動するようにすべてのライフサイクル ルールが設定されていることを確認してください (マニフェスト/アーカイブは問題ありません)。

マニフェスト ファイルに対するメタ情報アクセスの確認

考えられる原因: アーカイブされていないマニフェストのオブジェクト レベルのアクセスを取り消している

適用対象:

• Amazon S3

解決策: オブジェクトごとに、 aws s3api get-object-acl --bucket <bucket> --key <object> アーカイブされていないマニフェスト オブジェクトごとに許可の 1 つとして次の値を生成する必要があります。

{
   "Grantee": {
    "Type": "CanonicalUser",
    "DisplayName": "aws-slld",
    "ID": "669331f902bdea32b620b6e6c85123d153b5b30c8318b101d2fd202bc3906fe1"
    },
    "Permission": "FULL_CONTROL"
},

• Google Cloud Storage

解決策: オブジェクトごとに、 gsutil acl get <object> アーカイブされていないマニフェスト オブジェクトごとに許可の 1 つとして次の値を生成する必要があります。

{
    "email": "prod-lld-gcs-<member>@appnexus-cloud-export.iam.gserviceaccount.com",
    "entity": "user-prod-lld-gcs-<member>@appnexus-cloud-export.iam.gserviceaccount.com",
    "role": "OWNER"
}

でプレフィックスを作成する <path>

考えられる原因: 既にバケットまたはコンテナーに承認を適用していますが、マニフェストまたはフィード "フォルダー" を手動で作成しました。

適用対象: すべてのクラウド エクスポート構成

解決策:

手動で作成されたオブジェクトには、クラウド エクスポート システムへのアクセスを拒否する可能性がある異なる ACL があります。 手動で作成したマニフェストまたはフィード オブジェクトを削除してください。 Cloud Export システムは、必要なオブジェクトを独自に作成します。