クエリビルダー ブログシリーズ: パート 7 – クエリの検証

このブログシリーズでは、新しく改善されたインタラクティブ Google 広告クエリビルダー ツールの構築過程についてお伝えしています。シリーズのパート 6 では、クエリのフィールドの選択と選択解除の方法について説明しました。パート 7 では、ユーザーの選択に基づいてクエリを検証する方法について説明します。

背景

パート 5 ではフィールドの同時選択可否について説明し、パート 6 でも選択可否について少し触れました。それでも、クエリビルダーを使って無効な Google Ads Query Language（GAQL）文字列を作ることは可能です。それを対処するため、パート 6 で SelectionService に Observable をサブスクライブする ValidationService を作成します。Observable がトリガーされるたびに、一連の検証テストを実行してエラー メッセージの一覧を生成します。ValidationService には、別の Observable を作成し、検証が行われるたびに通知を受けるようにします。こうすることで、クエリにエラーが含まれている場合、ユーザーに通知できるようになります。ユーザーが何も選択していない場合は、アプリケーションが初期状態であることを示しているため、エラーは表示されません。

以下を確認する検証テストをします。

• SELECT 句にフィールドが含まれている
• コア日付の選択が有効である
• click_view の日付フィルタが有効である
• change_event と change_status の日付フィルタが有効である
• change_event と change_status の LIMIT が有効である

SELECT 句にフィールドが含まれている

有効な GAQL クエリには、SELECT 句に少なくとも 1 つの有効なフィールドが含まれている必要があります。選択されたのが SELECT 以外の句で、SELECT 句が空だった場合、エラーを生成します。

コア日付の選択が有効である

クエリのいずれかの句にコア日付セグメント（segments.date、segments.week、segments.month、segments.quarter、segments.year）がある場合、WHERE 句のフィルタ条件を組み合わせたときに、少なくとも 1 日の日付範囲を表すようなコア日付セグメントの有限な日付範囲ができなければなりません。クエリにコア日付セグメントが存在しない場合、エラーは生成されません。

それ以外の場合は、WHERE 句のコア日付セグメントによるフィルタを組み合わせたときに、有限の範囲になることを確認します。言い換えるなら、WHERE segments.date > ‘2021-01-01’ などのフィルタが 1 つしかない場合は、日付の範囲が閉じられていないので、失敗します。この場合はエラーが生成されます。ただし、WHERE segments.date > ‘2021-01-01’ AND segments.date < ‘2021-02-01’、WHERE segments.date = ‘2021-01-01’、WHERE segments.date DURING LAST_7_DAYS といったフィルタは有効です。この 3 つの例には開始日と終了日があるので、エラーは生成されません。

最後に、コア日付セグメントによるフィルタが有限の範囲になる場合、それを組み合わせたときに少なくとも 1 日の範囲になることをチェックします。たとえば、フィルタ条件 WHERE segments.date = ‘2021-01-01’ AND segments.date BETWEEN ‘2021-02-01’ AND ‘2021-03-01’ を含むクエリは、両方のフィルタ条件を満たす日付が存在しないので、失敗します。この場合はエラーが生成されます。ただし、フィルタ条件 WHERE segments.date BETWEEN ‘2021-01-01’ AND ‘2021-01-31’ AND segments.date >= ‘2021-01-15’ AND segments.date < ‘2021-03-01’ は有効です。すべてのフィルタ条件を満たす日付範囲は ‘2021-01-15’ – ‘2021-01-31’ なので、エラーは生成されません。

click_view の日付フィルタが有効である

click_view が FROM 句のメインリソースである場合、他の選択内容にかかわらず、WHERE 句に直近 90 日間の 1 日を指定する日付フィルタが存在しなければなりません。

change_event と change_status の日付フィルタが有効である

FROM 句のリソースが change_event または change_status である場合、「コア日付の選択が有効である」ルールと同じように、WHERE 句のフィルタ条件で有効な日付範囲が指定されている必要があります。ただし、この条件はクエリに日付フィールドがあるかどうか関係なく適用されます。さらに、コア日付セグメントではこのフィルタ条件は生成されません。FROM 句のメインリソースが change_event または change_status である場合、利用できるコア日付セグメントはないからです（パート 4 参照）。FROM 句のリソースが change_event である場合、Google Ads API サーバーで change_event.change_date_time フィールドのフィルタに対して日付の評価が行われます。FROM 句のリソースが change_status である場合、Google Ads API サーバーで change_status.last_change_date_time フィールドに対して日付の評価が行われます。

change_event と change_status の LIMIT が有効である

FROM 句のリソースが change_event または change_status である場合、クエリに有効な LIMIT、すなわち正の整数が含まれている必要があります。

まとめ

これで、GAQL クエリのエラーをチェックする ValidationService ができました。ValidationService では、GAQL 文字列が変更されるたびにこのチェックをし、エラーリストを生成して、Observable からイベントを発行します。エラーリストが空でない場合、この Observable をサブスクライブするコンポーネントでエラーアイコンを表示します。この投稿では、GAQL クエリ検証のさまざまな側面について説明しました。

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

Reviewed by Thanet Knack Praneenararat – Ads Developer Relations Team