ゼロ インプレッションと構成のレポート

AdWords API のデベロッパーは、掲載結果データを取得する以外にレポート システムを使ってアカウントの構成情報も取得しています。

このガイドではレポートのゼロ インプレッション データを解釈、管理する方法と、そうしたデータをアカウントの構成に役立てる方法を説明します。

レポートのゼロ インプレッション データ

広告が 1 度も表示されなかった場合、レポートでは表示回数が 0 回となります。さまざまな理由が考えられますが、たとえば広告が不承認となっているケースや、レポートの対象期間に広告が一時停止になっていた可能性があります。

掲載結果の算出でそうしたデータは役に立ちませんが、アカウントのすべての内容をダウンロードする際には欠かせません。

ゼロ インプレッション レポートは、アカウントの構成を確認する場合や API に対して get() の呼び出しを繰り返すことなくローカル データベースの同期をすばやく取る場合に便利です。レポートの結果にゼロ インプレッション データを含めることにより、アカウントの構成を 1 回の呼び出しで確認することができます。

ゼロ インプレッション データの追加と除外

ゼロ インプレッション データは通常の掲載結果レポートには普通に表示されるため、自分自身の目的に合わせてそのデータを含めるか、除外するか明示的に指定する必要があります。これでリクエストの内容が明確になり、リクエストでレポート フィールドの指定とゼロ インプレッションへの対応が矛盾している場合に、API から意味のあるエラーを返すことができます。

ゼロ インプレッション データを含める場合

ゼロ インプレッション データはアカウントの構成を 1 回の呼び出しで確認する場合に便利です。API 呼び出しを繰り返す方法もありますが、レート制限に達する恐れがあります。

たとえば、キーワードの掲載結果レポートIdCriteria を確認する場合にゼロ インプレッション データを除外すると、最小限の結果だけが返されます。一方、ゼロ インプレッション データを含めて CampaignIdAdGroupId などのフィールドを追加すると、すでに使用しているキーワードの構成レポートを作成することができます。

ゼロ インプレッション データを除外する場合

ゼロ インプレッション データはアカウントの要素の構成を確認する場合に便利ですが、通常は掲載結果レポートから除外します。ゼロ インプレッション データを除外すると、返されるデータの量が少なくなり、特定の期間の有益な掲載結果データだけを取得できます。多くのキャンペーンが一時停止になっている場合はゼロ インプレッション データで結果セットが必要以上に大きくなることがあるので、除外を選択することをおすすめします。

ゼロ インプレッション データを含める

レポートの出力にゼロ インプレッション データを含めるには、includeZeroImpressions HTTP ヘッダーを true に設定します。

true に設定すると、レポートの行が指標の値に基づいて除外されることがなくなり、レポートにゼロ インプレッション データが含まれるようになります。

ゼロ インプレッション データを除外する

ゼロ インプレッション データは、2 通りの方法でレポートから明示的に除外できます。

  • includeZeroImpressions HTTP ヘッダーを false に設定します。
  • 述語関数を使用します。

includeZeroImpressions HTTP ヘッダーを false に設定する

ゼロ インプレッション データを除外する最も簡単な方法は、includeZeroImpressions HTTP ヘッダーを false に設定することです。

false に設定すると、リクエストした Metric フィールドの少なくとも 1 つが非ゼロである行だけが返されます。

述語関数でゼロ インプレッション データを除外する

ゼロ インプレッション データは、演算子 GREATER_THAN と値 0 を指定した Impressions フィールドの述語関数で除外できます。

この述語関数の XML は次のようになります。

<predicates>
  <field>Impressions</field>
  <operator>GREATER_THAN</operator>
  <values>0</values>
</predicates>

AWQL ステートメントは次のようになります。

WHERE Impressions > 0

ゼロ インプレッション データを暗黙的に除外する

レポートのリクエストにゼロ インプレッションに非対応のフィールドが含まれている場合、ゼロ インプレッションの行は明示的な指定がなくても除外されます。レポートタイプのページの Supports Zero Impressions 属性で、各フィールドのゼロ インプレッションへの対応を確認できます。

ただし、リクエストのフィールドを 1 つ追加または削除するだけでもレポートの動作に影響があるので、暗黙的な除外には頼らない方が得策です。

構成レポート

アカウントの規模が大きいほど、API のサービスを使用してアカウントの総合的なデータを収集するのに大量のリクエストが必要となります。

AdWords のレポートは、アカウントとその関連要素の基本的な構成情報を取得する簡単な方法を提供します。レポートを使ってオブジェクト ID、名前、値などのデータをすぐに返し、アカウントの基本構造を再現できます。その情報を元に、詳細を確認したい要素を特定したり、オブジェクト ID を使用して API から詳細情報を取得したりすることが可能です。

レポートタイプのページでは、アカウント オブジェクトごとにどの列エントリを取得できるか確認できます。そうした列のヘッダーも ReportDefinitionService の getReportFields() メソッドを使用して、自動的に取得可能です。レポートの列を慎重に選ぶことで、アカウントの構造を構築できる十分な情報を入手できます。

広告グループ条件を取得する

AdWords アカウントには多数の広告グループ基準があるため、AdGroupCriterionService に対する getquery リクエストの発行は、CRITERIA_PERFORMANCE_REPORT を介して同じ条件を取得する場合に比べて非効率的です。

構造レポートとして CRITERIA_PERFORMANCE_REPORT を使用するには、リクエストが次の制限を満たすようにしてください。

  1. レポート リクエスト内の選択されたすべてのフィールドには、ATTRIBUTEfieldBehavior がある。
  2. レポート リクエストの述語関数に使用されるすべてのフィールドには、ATTRIBUTEfieldBehavior がある。
  3. includeZeroImpressions HTTP ヘッダーが true に設定されている。
  4. リクエストに期間または DURING 句が含まれていない。

たとえば、次の AWQL は、アカウントの各広告グループ条件の広告グループ ID、条件 ID、条件タイプ、条件説明、およびターゲット タイプを取得します。

SELECT AdGroupId, Id, CriteriaType, Criteria, IsNegative FROM CRITERIA_PERFORMANCE_REPORT

キャンペーン条件を取得する

CAMPAIGN_CRITERIA_REPORT を使うと、アカウント内のキャンペーン単位のすべての条件を取得できます。CRITERIA_PERFORMANCE_REPORT とは異なり、CAMPAIGN_CRITERIA_REPORT は構造レポートとしてのみ使用できます。

たとえば、次の AWQL は、アカウントの各キャンペーン条件のキャンペーン ID、条件 ID、条件タイプ、条件説明、およびターゲット タイプを取得します。

SELECT CampaignId, Id, CriteriaType, Criteria, IsNegative FROM CAMPAIGN_CRITERIA_REPORT

キャンペーンの例

この例ではアカウントの各キャンペーンに関するデータの収集方法を示します。AWQL リクエストを使ってデータを収集し、そのデータをローカルのデータベースに保存します。これでローカルの SELECT リクエストにより、必要な構成表を作成できます。

次の手順とコード スニペットで、キャンペーンの表の作成方法を示します。

  1. AWQL リクエストを作成し、キャンペーンの掲載結果レポートから取得するすべての列ヘッダーを指定して、キャンペーンのデータを問い合わせます。レポートのタイプと対象期間も指定してください。続いてこのクエリを使用し、ダウンロード形式に CSV を指定してレポートを作成します。

    SELECT CampaignStatus, CampaignId, CampaignName, ExternalCustomerId,
        CustomerDescriptiveName, Amount, BiddingStrategyId, Impressions
    FROM CAMPAIGN_PERFORMANCE_REPORT
    DURING YESTERDAY
    

  2. ローカルにキャンペーンの表を作成します。このステートメントではキャンペーンの表が作成され、SQLite 表には列のヘッダーとタイプが表示されます。

    CREATE TABLE campaigns (Status STRING, id LONG, name STRING, extCID LONG,
        custName STRING, amount FLOAT, biddingStrategyId LONG, impressions INTEGER)
    

  3. キャンペーンの表に情報を入力します。次の SQL ステートメントは campaigns の表にエントリを挿入します。各「?」のパラメータ値はレポートのダウンロードで取得した値を使って設定します。

    INSERT INTO campaigns (Status, id, name, extCID, custName, amount,
        biddingStrategyId, impressions) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
    

レポートの形式

レポートは CSV や XML などさまざまな形式で入手できますが、CSV 形式であれば、すぐに利用可能なライブラリを通じてレスポンス ストリームを利用し、選択したオブジェクト形式へのデータ入力に細かくフィルタをかけることができます。CSV の出力は簡潔にまとまっているので、処理に時間がかかりません。

デフォルトの CSV レポートは 1 行目にレポートのヘッダーがあり、2 行目の列ヘッダーに続いて結果が表示され、最後にまとめの Total 行があります。次に示しているのはキャンペーンの掲載結果レポートからのレスポンスです(デフォルトの状態)。

"CAMPAIGN_PERFORMANCE_REPORT (Apr 1, 2015-Apr 6, 2015)"
Campaign state,Campaign ID,Campaign,Customer ID,Account,Cost,Bid Strategy Name,Impressions
paused,143072203,Search + DSAs,1234567890,My AdWords Account,0, --,0
paused,168682400,Interplanetary Cruise 1396462861759,1234567890,My AdWords Account,0, --,0
paused,168682099,Interplanetary Cruise 1396462699054,1234567890,My AdWords Account,0, --,0
enabled,238539688,Campaign 1234,1234567890,My AdWords Account,5970000, --,902
Total, --, --, --, --,5970000, --,902

このデフォルトのレポートでは、レポート ヘッダー行の次の2 行目に、リクエストした列の名前が表示されています。出力における列の順序はリクエストで指定した順序と同じですが、列の指定に重複がある場合は 2 つ目が省略されます。レポートの最後は集計の行です。

データを解析してデータベースに入力する際には、最初の 2 行と最後の Total 行を無視し、その間の各行を入力するようにしてください。あるいはリクエストで任意指定のヘッダーを設定すると、レスポンスからレポート ヘッダー、列ヘッダー、集計行が省略されてデータだけになります。

この作業を広告グループ、広告、条件ごとに行うと、ローカルのデータベースにデータが入力されて SQL のクエリを発行できるようになります。このサンプルは収集したデータの実際の利用方法に合わせて修正できます。たとえば次のように修正することが可能です。

SELECT * FROM campaigns
LEFT OUTER JOIN adGroups ON campaigns.id=adGroups.campaignId
LEFT OUTER JOIN ads ON ads.adAdGroupId=adGroups.adGroupId

または

SELECT * FROM criteria
JOIN keywords
WHERE criteria.critType='Keyword' AND keywords.keywordId=criteria.critId

役立つヒント

この方法でアカウントのデータを取得する際には、次の点に注意してください。

  • 特定のレポートをリクエストする際に、ゼロ インプレッション データのある行を除外する列を指定すると、いかなる結果も返されません。広告掲載結果レポートKeywordId フィールドはそうした例のひとつであり、そのことはこのフィールドの Notes 列や Support Zero Impressions 列の False 値で確認できます。また、ConversionTypeNameClicks など相互に排他的な列もあります。構成データをダウンロードする際にはこうした列ヘッダーを使用せず、代わりに Behavior 列で Attribute としてリストされているものを使ってください。

  • リクエストでは列を重複させないようにしてください。重複した列はレスポンスから削除されるため、データの解析に支障を来す可能性があります。レポートタイプのページの Notes 列で、列の書式の仕様を確認してください。

  • 任意指定のヘッダーを使ってまとめの Total 行を省略する方策は採らず、「Total」という単語の存在によって解析の終わりを示す場合は、AWQL クエリで最初の列を慎重に選んでください。「Total」という単語がその列の値として認識されてしまうと、解析が中途半端で終わってしまいます。たとえば値が Long 型である ID は最初の列として問題なく使用できます。上記の例では Status 列を選択しましたが、この列は String 型で使用できる値に制限があります。

  • 各列では必ず適切な型のデータを取得してください。文字列から適切な値に解析する必要がある場合に、予期せぬデータを受け取って、そのまま文字列専用のパーサーを呼び出すと例外が返されます。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。