var report = AdsApp.report(query, {apiVersion: 'v7'});

var results = AdsApp.search(query, {apiVersion: 'v7'});

このブログシリーズでは、新しく改善されたインタラクティブ Google 広告クエリビルダー ツールの構築過程についてお伝えしています。シリーズのパート 4 では、ResourceService を作成し、アプリ内のユーザーのロケーションによって決まる FROM 句のリソースをもとにして関連フィールドを表示する方法について説明しました。パート 5 では、Google Ads Query Language（GAQL）クエリ文字列でフィールドが選択できるかどうかを決定する方法について説明します。

背景と目的フィールドが選択できるかどうか、すなわち、GAQL 文字列の句を追加できるかどうかは、1）FROM 句におけるメインリソースの固有のプロパティとそのフィールドのプロパティ、2）GAQL クエリ文字列の現在の状態、という 2 つによって決まります。ユーザーに選択可能なフィールドとして表示されるのは固有のプロパティだけなので、項目（1）にはパート 4 で作成した ResourceService で対処できます。

項目（2）に対処するために、SelectionService という新しいサービスを作成します。このサービスの役割は、選択可否の判断、フィールドの選択、フィールドの選択解除などです。この投稿では、フィールドの選択可否の判断について説明します。SelectionService によるフィールドの選択と選択解除の方法については、シリーズのパート 6 で説明します。
フィールドの同時利用性すべてのフィールドを同時に利用できるとは限りません。2 つのフィールドを同時に利用できる場合、両方のフィールドが 1 つの GAQL 文字列内に共存できます。2 つのフィールドを同時に利用できない場合は、2 つのフィールドのどちらかのみを GAQL 文字列のいずれかの句に含めることができます。そのため、評価対象のフィールドとは同時に利用できないフィールドが GAQL 文字列内にある場合、評価対象のフィールドは選択不可となります。UI はそれを反映し、対応するエラー メッセージをユーザーに表示します。





実装
incompatibleSelected というインスタンス変数で、メインリソースの各フィールドについて、同時に選択できないフィールドのうち現在選択されているものを追跡します。この変数は、それぞれのフィールドを、同時に選択できないフィールドのうち現在選択されているものの一覧を表す Set にマッピングします。

interface IncompatibleSelected: {[key: string]: Set<string>}

この incompatibleSelected を初期化して、ResourceService で求めたリソースのすべてのフィールドがマップのキーになるように、また各エントリの値が空の Set になるようにします。

フィールドが選択されると、incompatibleSelected の Set（選択されたフィールドと同時に選択できないフィールドの集合）に、選択されたフィールドを追加します。たとえば、FROM 句のリソースが ad_group であるとします。segments.ad_destination_type は、metrics.absolute_top_impression_percentage や metrics.active_view_cpm などとは同時に選択できません。次の表は、これらのフィールド間の同時選択性の関係を示しています。

incompatibleSelected = {
  …
  'segments.ad_destination_type': {},
  'metrics.absolute_top_impression_percentage': {'segments.ad_destination_type'}
  'metrics.active_view_cpm': {'segments.ad_destination_type'}
  ...
}

  isSelectable(field: string): boolean {
    return this.incompatibleSelected[field]?.size === 0;
  }

まとめ以上で、フィールドが選択可能かどうかを判断する SelectionService のロジックを実装できました。ユーザーにフィールドを表示する際には、isSelectable(field) を呼び出すだけで、UI に表示するものを決めることができます。今回の投稿では、フィールドの同時選択性と、フィールドが選択できるかどうかに関する内容を説明しました。パート 6 では、このセクションの内容をもとに、フィールドの選択や選択解除が行われたときに、SelectionService で GAQL クエリ文字列の状態を追跡する方法について説明します。

Google Ads API での GAOL クエリの構築についての理解が深まれば幸いです。ご質問やさらにサポートが必要なことがありましたら、フォーラムまたは googleadsapi-support@google.com にご連絡ください。

- Devin Chasanoff（Google Ads API チーム）

• GAQL は、Google Ads API からデータを取得する柔軟で充実したメカニズムです。その力を最大限に引き出し、効率的にクエリを作成するには、クエリ言語の細かい点までしっかりと理解しておくことが重要です。
• 以前のバージョンのインタラクティブ Google 広告クエリビルダー ツールは、GAQL のクエリ文字列の作成に役立ちました。しかし、ツールの背後にあるロジックの一部を公開して GAQL クエリ文字列の検証の仕組みについて理解を深めてもらうことで、クエリの作成プロセスを高速化する余地がありました。

• リソース スキーマの設計 : インタラクティブ クエリビルダー Angular アプリケーションの正規データセットとして利用する詳細な JSON リソース スキーマの設計。
• リソース スキーマの作成 : そのアプリケーションの構築を簡単にするため、GoogleAdsFieldService を使って、同時に利用できないフィールドを含む拡張リソース スキーマを作成する方法。
• リソース サービスの作成 : アプリケーションのさまざまな部分で、どのフィールドがユーザーに表示されるかを決めるリソース サービスを作成する方法。
• フィールドの選択可否の決定 : Google Ads Query Language（GAQL）のクエリ文字列の句で、フィールドが選択可能かどうかを決める選択サービスを作成する方法。
• フィールド選択とクエリ検証 : 選択サービスを更新し、フィールドの選択と GAQL 文字列の検証をする方法。
• 概要 : このプロセスから学んだ重要な教訓の概要。