AdWords API v201101 の新機能 - ジェネリックセレクタのご紹介
2011年5月17日火曜日
石原 直樹 AdWords API チーム
さて、先日ご紹介させていただいた 新しいバージョンの AdWords API ですが、開発者向けのさまざまな新機能が満載です。これから数回に分けてそれぞれの特徴を説明していきたいと思います。
AdWords API v201101 では、get() メソッドを使ってデータを取得する方法が改善され、ジェネリックセレクタが導入されました。今回はその新機能についての詳しい説明と既存のコードをジェネリックセレクタに移行する方法について解説いたします。
はじめに
v201101 以前の AdWords API では、すべてのサービスに固有のセレクタがあり、get() メソッドを使用してデータを取得していました。たとえば、ある広告グループの中のアクティブな広告グループクライテリアを取得したい場合、以下のようなコードを書かれていたでしょう。
// v201008 (古いバージョン用)のコード
// セレクタを作成
// ID フィルタを作成
// 広告グループクライテリアのすべてを取得
これは簡単ではありますが、個々のサービスは固有のセレクタを持っているので使いたいサービスそれぞれのセレクタについて知る必要があります。また、フィルタリングのオプションはセレクタのフィールドとして指定されますから、AdWords API で新しいフィルタのサポートを開始する際、セレクタにも変更が及びました。これがすべてのバージョンに対して正しく行われる必要がありました。
一方、 レポートで使用されているセレクタモデルはもっと柔軟です。フィールドのリストを指定でき、プレディケイト (predicate) を使用して Filterable なフィールドでいくらでもフィルタを追加できます。複数の演算子を使うこともできます。(ただし、上記のコードにあるような明示的でない EQUALS は除きます。）また、フィールド名が SOAP スキーマから切り離されているので、新しい選択可能でフィルタ可能なフィールドを追加することも可能です。さらに、レポートを作成するコードと、ダウンロードするためのコードは同じままです。v201101では、このデザインを取り上げ、全サービスに適用することにしました。
AdWords API の v201101 を使えば、ある広告グループにある、すべてのアクティブな広告グループクライテリオンを以下のように取得することができます。
// v201101 (新しいコード)
// セレクタを作成
// フィルタリングする条件を設定
// すべての広告グループクライテリアを取得
セレクタのプロパティを理解
セレクタの主なプロパティは以下のとおりです。
Fields: オブジェクトを取得するのにジェネリックセレクタを使用する際、デフォルトではサーバーはすべてのフィールドは返しません。リクエストされたフィールド群しか返しません。オブジェクトの他のフィールドは未定義、あるいは null がセットされていますが、それはお使いのプログラミング言語によります。Field というプロパティ値はサーバーから返されるべきフィールドのリストを指定するために使うことができます。エンティティの中のどの選択可能な (Selectable) フィールドも使用することができます。たとえば、CampaignService を使う時、Campaign の中の Selectable なフィールドはどれでも使用することができます。たとえば、Campaign.name は Selectable なフィールドとしてマークされており、セレクタのフィールド名が "Name"と指定されるものです。このようにフィールド中のエントリとして使うことができるわけです。
ただし、オブジェクトが他のオブジェクトを参照するフィールドを持っている場合は注意が必要です。その場合、プロパティは Selectable としてマークされません。サブフィールドが Selectable としてマークされます。たとえば、Campaign.budget は Budget 型のプロパティですので、Campaign.budget は Selectable ではありません。キャンペーンの budget フィールドを取得するには、Budget オブジェクトの Selectable なフィールドをリクエストする必要があります。
Predicates: predicate を使用することで、返ってきたデータをフィールド値によってフィルタすることができます。predicate では、エンティティから、どの Filterable フィールドでも使うことができます。様々な operators もフィルタリング条件を指定するのに使用可能です。さらに、複数の predicate を単一のセレクタで使用する際、predicate で指定された条件は AND としてフィルタ条件で扱われることになります。
個々のサービスプロバイダは、サービス固有のフィールドを持っていますが、ジェネリックセレクタでは、Predicate により使用可能です。例えば、CampaignId は AdGroupAdService のメンバではありませんが、で、CampaignId を predicate のフィールドとして使用可能です。ジェネリックセレクタフィールドのリストは、こちらの selector migration guide を参照ください。
DateRange: オプショナルとして、DateRange を追加して、どの日付のデータを取得すべきかコントロールすることができます。日付の指定は、サーバーから返答された統計値にのみ影響し、エンティティ(オブジェクト）に影響するわけではありません。日付のフォーマットは min と max 値の二つとも yyyymmdd の形になります。日付のは以下の範囲内でなければなりません。[19700101, 20380101]
Ordering: オーダーフィールドを指定することで、データをソートしたい(昇順でも降順でも)フィールドを定められます。order フィールドを指定する OrderBy オブジェクトを並べる順番は重要です。最初の要素が最初のソート順を決めます。2つ目の要素で二番目のソートが決まります。以下、同様にソートされていきます。
Paging: ページングフィールドを使用することで、返却される結果をどこからはじめるか、ページごとにいくつ結果を入れるかを指定することができます。
サービスーバー固有のセレクタからジェネリックセレクタへの移行
CampaignSelector のようなサービス固有のセレクタは v201101 以後ではサポートされません。ですから、AdWords API v201101 に移行される際は、コードを修正いただきジェネリックセレクタを使用していただく必要があります。selector migration guide をご覧いただき、個々のサービス固有セレクタごとのフィールドのマッピングをご確認ください。また、ジェネリックセレクタが採用されていないサービスが若干存在しますが、将来の AdWords API バージョンで採用される予定です。
ジェネリックセレクタのサポートを全てのクライアントライブラリでサポートしております。新しい機能を存分に活用し、ご感想をこちらのフォーラム (英語)でお知らせください。
さて、先日ご紹介させていただいた 新しいバージョンの AdWords API ですが、開発者向けのさまざまな新機能が満載です。これから数回に分けてそれぞれの特徴を説明していきたいと思います。
AdWords API v201101 では、get() メソッドを使ってデータを取得する方法が改善され、ジェネリックセレクタが導入されました。今回はその新機能についての詳しい説明と既存のコードをジェネリックセレクタに移行する方法について解説いたします。
はじめに
v201101 以前の AdWords API では、すべてのサービスに固有のセレクタがあり、get() メソッドを使用してデータを取得していました。たとえば、ある広告グループの中のアクティブな広告グループクライテリアを取得したい場合、以下のようなコードを書かれていたでしょう。
// v201008 (古いバージョン用)のコード
// セレクタを作成
AdGroupCriterionSelector selector = new AdGroupCriterionSelector();
selector.userStatuses = new UserStatus[] {UserStatus.ACTIVE};
// ID フィルタを作成
AdGroupCriterionIdFilter idFilter = new AdGroupCriterionIdFilter();
idFilter.adGroupId = adGroupId;
selector.idFilters = new AdGroupCriterionIdFilter[] {idFilter};
// 広告グループクライテリアのすべてを取得
AdGroupCriterionPage adGroupCriterionPage = adGroupCriterionService.get(selector);
これは簡単ではありますが、個々のサービスは固有のセレクタを持っているので使いたいサービスそれぞれのセレクタについて知る必要があります。また、フィルタリングのオプションはセレクタのフィールドとして指定されますから、AdWords API で新しいフィルタのサポートを開始する際、セレクタにも変更が及びました。これがすべてのバージョンに対して正しく行われる必要がありました。
一方、 レポートで使用されているセレクタモデルはもっと柔軟です。フィールドのリストを指定でき、プレディケイト (predicate) を使用して Filterable なフィールドでいくらでもフィルタを追加できます。複数の演算子を使うこともできます。(ただし、上記のコードにあるような明示的でない EQUALS は除きます。）また、フィールド名が SOAP スキーマから切り離されているので、新しい選択可能でフィルタ可能なフィールドを追加することも可能です。さらに、レポートを作成するコードと、ダウンロードするためのコードは同じままです。v201101では、このデザインを取り上げ、全サービスに適用することにしました。
AdWords API の v201101 を使えば、ある広告グループにある、すべてのアクティブな広告グループクライテリオンを以下のように取得することができます。
// v201101 (新しいコード)
// セレクタを作成
Selector selector = new Selector();
selector.fields = new string[] {"Id", "AdGroupId", "KeywordText", "Status"};
// フィルタリングする条件を設定
Predicate adGroupPredicate = new Predicate();
adGroupPredicate.field = "AdGroupId";
adGroupPredicate.@operator = PredicateOperator.EQUALS;
adGroupPredicate.values = new string[] {adGroupId.ToString()};
Predicate statusPredicate = new Predicate();
statusPredicate.field = "Status";
statusPredicate.@operator = PredicateOperator.EQUALS;
statusPredicate.values = new string[] {UserStatus.ACTIVE.ToString()};
selector.predicates = new Predicate[] {adGroupPredicate, statusPredicate};
// すべての広告グループクライテリアを取得
AdGroupCriterionPage adGroupCriterionPage = adGroupCriterionService.get(selector);
セレクタのプロパティを理解
セレクタの主なプロパティは以下のとおりです。
Fields: オブジェクトを取得するのにジェネリックセレクタを使用する際、デフォルトではサーバーはすべてのフィールドは返しません。リクエストされたフィールド群しか返しません。オブジェクトの他のフィールドは未定義、あるいは null がセットされていますが、それはお使いのプログラミング言語によります。Field というプロパティ値はサーバーから返されるべきフィールドのリストを指定するために使うことができます。エンティティの中のどの選択可能な (Selectable) フィールドも使用することができます。たとえば、CampaignService を使う時、Campaign の中の Selectable なフィールドはどれでも使用することができます。たとえば、Campaign.name は Selectable なフィールドとしてマークされており、セレクタのフィールド名が "Name"と指定されるものです。このようにフィールド中のエントリとして使うことができるわけです。
ただし、オブジェクトが他のオブジェクトを参照するフィールドを持っている場合は注意が必要です。その場合、プロパティは Selectable としてマークされません。サブフィールドが Selectable としてマークされます。たとえば、Campaign.budget は Budget 型のプロパティですので、Campaign.budget は Selectable ではありません。キャンペーンの budget フィールドを取得するには、Budget オブジェクトの Selectable なフィールドをリクエストする必要があります。
Predicates: predicate を使用することで、返ってきたデータをフィールド値によってフィルタすることができます。predicate では、エンティティから、どの Filterable フィールドでも使うことができます。様々な operators もフィルタリング条件を指定するのに使用可能です。さらに、複数の predicate を単一のセレクタで使用する際、predicate で指定された条件は AND としてフィルタ条件で扱われることになります。
個々のサービスプロバイダは、サービス固有のフィールドを持っていますが、ジェネリックセレクタでは、Predicate により使用可能です。例えば、CampaignId は AdGroupAdService のメンバではありませんが、で、CampaignId を predicate のフィールドとして使用可能です。ジェネリックセレクタフィールドのリストは、こちらの selector migration guide を参照ください。
DateRange: オプショナルとして、DateRange を追加して、どの日付のデータを取得すべきかコントロールすることができます。日付の指定は、サーバーから返答された統計値にのみ影響し、エンティティ(オブジェクト）に影響するわけではありません。日付のフォーマットは min と max 値の二つとも yyyymmdd の形になります。日付のは以下の範囲内でなければなりません。[19700101, 20380101]
Ordering: オーダーフィールドを指定することで、データをソートしたい(昇順でも降順でも)フィールドを定められます。order フィールドを指定する OrderBy オブジェクトを並べる順番は重要です。最初の要素が最初のソート順を決めます。2つ目の要素で二番目のソートが決まります。以下、同様にソートされていきます。
Paging: ページングフィールドを使用することで、返却される結果をどこからはじめるか、ページごとにいくつ結果を入れるかを指定することができます。
サービスーバー固有のセレクタからジェネリックセレクタへの移行
CampaignSelector のようなサービス固有のセレクタは v201101 以後ではサポートされません。ですから、AdWords API v201101 に移行される際は、コードを修正いただきジェネリックセレクタを使用していただく必要があります。selector migration guide をご覧いただき、個々のサービス固有セレクタごとのフィールドのマッピングをご確認ください。また、ジェネリックセレクタが採用されていないサービスが若干存在しますが、将来の AdWords API バージョンで採用される予定です。
ジェネリックセレクタのサポートを全てのクライアントライブラリでサポートしております。新しい機能を存分に活用し、ご感想をこちらのフォーラム (英語)でお知らせください。