1. はじめに
この Codelab では、Content API for Shopping と AdWords API の基本的な操作方法を学び、両方を使用するアプリを作成します。具体的には、AdWords アカウントと Merchant Center アカウントを作成してリンクするコマンドライン アプリケーションを構築します。
学習内容
- MCC アカウントで管理される AdWords アカウントを作成する方法。
- マルチクライアント アカウントで管理される Merchant Center アカウントを作成する方法。
- Merchant Center アカウントから AdWords アカウントへのリンクをリクエストする方法。
- AdWords アカウントで保留中の Merchant Center リンクを承認する方法。
必要なもの
- AdWords クライアント センター（MCC）アカウント
- Merchant Center マルチクライアント アカウント
- Java 7 以降
- Maven
- サンプルコード
- テキスト エディタ（Maven プロジェクトを理解する IDE（Eclipse や IntelliJ など）をおすすめします）
2. 設定方法
コードをダウンロードする
次のリンクをクリックして、この Codelab 用のコードすべてをダウンロードします。
ダウンロードした zip ファイルを解凍すると、ルートフォルダ（shopping-account-linking-master）が展開されます。このフォルダには、Maven プロジェクトと必要なすべてのリソースが含まれています。特に注目すべきサブディレクトリは次のとおりです。
src/main/javaは Maven プロジェクトのソースルートであり、作業用のコード スケルトンが含まれています。src/main/java/solutionには、完成したソリューションが格納されています。
必要なパッケージをインストールしてビルドする
Eclipse や IntelliJ などの Maven 対応 IDE を使用している場合は、抽出したフォルダを Maven プロジェクトとしてインポートし、通常どおりプロジェクトをコンパイルできます。
コマンドラインから Maven を使用している場合は、次のコマンドを実行して、必要なパッケージを取得し、解凍したプロジェクトのルートフォルダ（shopping-account-linking-master）からプロジェクトをコンパイルできます。
mvn compile
3. 認証を設定する
このステップでは、コーディングは行わず、AdWords API と Content API for Shopping の適切な認証トークンを含むファイルを設定します。
AdWords API の認証を設定する
この Codelab では、クライアント ライブラリと同じ認証情報の読み込みを使用します。そのため、クライアント センター アカウントで Java 用 Google Ads API クライアント ライブラリを使用している場合は、すでに設定されているはずです。そうでない場合は、手順 1 ～ 3 に沿って、Java 用 Google 広告 API クライアント ライブラリの使用を開始します。
Content API の認証を設定する
サービス アカウント キーがない場合は、次の操作を行います。
- マルチクライアント アカウントの Merchant Center に移動し、オーバーフロー メニュー（
）から [Content API] を選択します。 - [認証] を選択し、青い [+] ボタン
をクリックします。 - Google Cloud Platform と Google APIs の利用規約に同意すると、新しいサービス アカウント キーを含む JSON ファイルがブラウザに自動的にダウンロードされます。
次に、サービス アカウントを使用してショッピング サンプルの認証を設定する手順を行います。つまり、サービス アカウント キーのコピーは、ホーム ディレクトリの shopping-samples/content/service-account.json パスに配置する必要があります。この Codelab の終了後にサンプルを試す予定がない限り、サンプルの構成を設定する必要はありません。
テストする
認証トークンが適切な場所に配置されたので、サンプルを実行してみましょう。コマンドラインで Maven を使用している場合は、次のコマンドを実行します。
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
セッション オブジェクトが指定されていないというエラー メッセージが表示された場合は、認証トークンが設定され、正しく機能しています。エラー メッセージには、機能しなかった認証情報と修正する必要があるファイルが表示されます。
4. API に接続する
使用する 2 つの API の有効な認証トークンを取得したので、実際のコードに移りましょう。まず、認証トークンを使用してセッション オブジェクトを作成します。後続のステップでは、これらのセッション オブジェクトを使用して、各 API が提供するさまざまなサービスとメソッドにアクセスします。
Content API セッション オブジェクトを作成する
Content API セッションを作成するには、ShoppingContent.Builder オブジェクトを作成し、それを使用して適切な ShoppingContent オブジェクトを作成します。幸い、前者を構築するために必要なものはすべてコード スケルトン内にすでに用意されているため、次のようにまとめるだけです。
SolutionRunner.java
// TODO(sessions): Create a ShoppingContent object using ShoppingContent.Builder.
contentApiSession =
new ShoppingContent.Builder(httpTransport, jsonFactory, contentApiCredential)
.setApplicationName("Linking AdWords and Merchant Center Accounts Codelab")
.build();
アプリ名の設定は必須ではありませんが、build() メソッドを呼び出す前に ShoppingContent.Builder オブジェクトを使用して必要なオプションを設定する方法を示しています。
AdWords API セッション オブジェクトを作成する
同様に、AdWordsSession オブジェクトを構築するための AdWordsSession.Builder クラスがあります。ここでの主な違いは、ビルダーに構成オプションを直接設定するのではなく、fromFile() メソッドを使用して、前の手順で設定した ads.properties ファイルから構成オプションを読み込むことです。
SolutionRunner.java
// TODO(sessions): Create a AdWordsSession object using AdWordsSession.Builder.
adWordsSession =
new AdWordsSession.Builder()
.fromFile()
.withOAuth2Credential(adwordsOAuth2Credential)
.build();
テストする
コマンドラインから Maven プロジェクトを実行する場合は、前のセクションと同じコマンドを使用して Maven プロジェクトを再ビルドして実行します。
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
今回はエラーは発生しませんが、特に興味深い出力も得られません。API を呼び出して新しいアカウントを作成してリンクするときに、この値を追加します。
5. 新しい管理対象 AdWords アカウントを作成する
API セッション オブジェクトを作成したので、リンクするアカウントを作成します。まず、MCC アカウントにテスト用 AdWords アカウントを作成します。
ManagedCustomerService にアクセスする
AdWords API では、まず静的 getInstance() メソッドを使用して AdWordsServices クラスのインスタンスを取得し、利用可能なさまざまなサービスにアクセスします。このインスタンスを使用して、get() メソッドでこれらのサービスのクライアントを作成できます。このメソッドは、クライアントを作成するセッションと目的のサービスのインテフェースの 2 つの引数を受け取ります。
SolutionRunner.java
// TODO(newAWaccount): Using the ManagedCustomerService, create a new testing AdWords account
// under the given manager account.
AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();
ManagedCustomerServiceInterface managedCustomerService =
adWordsServices.get(adWordsSession, ManagedCustomerServiceInterface.class);
ここでは、ManagedCustomerService にアクセスします。これにより、特定の MCC アカウントから AdWords の「顧客」（アカウント）を管理できます。
新しいアカウント設定を指定する
まず、新しいアカウントの設定を含む ManagedCustomer オブジェクトを作成します。この Codelab では、テスト用アカウントを作成し、通貨を米ドルに、タイムゾーンを米国西海岸と同じに設定します。
SolutionRunner.java
Random rand = new Random();
long run = rand.nextLong();
ManagedCustomer newAdWordsAccount = new ManagedCustomer();
newAdWordsAccount.setName(String.format("AdWords Account Created by Run %d", run));
newAdWordsAccount.setTestAccount(true);
newAdWordsAccount.setCurrencyCode("USD");
newAdWordsAccount.setDateTimeZone("America/Los_Angeles");
また、アカウント名に含める乱数も作成します。これは、ここで作成する Google 広告アカウントと後で作成する Merchant Center アカウントを照合し、ソリューションが完成した後に両方のアカウントを視覚的に検査して、実際にリンクされていることを確認できるようにするためです。
新しい管理対象アカウントを作成する
実際に新しいアカウントを作成するには、ManagedCustomerOperation を使用して ADD オペレーションを指定します。
SolutionRunner.java
ManagedCustomerOperation operation = new ManagedCustomerOperation();
operation.setOperand(newAdWordsAccount);
operation.setOperator(Operator.ADD);
次に、ManagedCustomerService オブジェクトの mutate() メソッドを使用してオペレーションを実行します。このメソッドは、実行するオペレーションの配列を受け取りますが、ここでは 1 つのオペレーションのみを実行します。mutate() メソッドの結果は、ManagedCustomer のリストを含む値です。ここでは、作成した新しいアカウントである 1 人の顧客を含むリストになります。新しいアカウントの ID を取得して今後使用できるようにします。また、出力として表示できるように出力します。
SolutionRunner.java
ManagedCustomerReturnValue result =
managedCustomerService.mutate(new ManagedCustomerOperation[] {operation});
Long adWordsId = result.getValue()[0].getCustomerId();
System.out.printf("Created new AdWords account %d%n", adWordsId);
テストする
前回と同様に、ソリューションを実行してみてください。コマンドラインから Maven を使用している場合:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
問題がなければ、エラーは表示されず、作成した新しい AdWords アカウントの ID が表示されます。MCC アカウントの AdWords サイトにアクセスすると、新しいアカウントも表示されます。
6. 新しい Merchant Center サブアカウントを作成する
このステップでは、前回のステップで作成した Google 広告アカウントにリンクする Merchant Center サブアカウントを作成します。サブアカウントの作成後にリンクを別途リクエストするのではなく、対応する AdWords アカウントの ID がすでにあるため、作成時にリンクをリクエストできます。
新しいサブアカウントの設定を指定する
AdWords API とは異なり、Account モデルクラスの setter はオブジェクトを返すため、新しい Account オブジェクトで呼び出しを連結できます。Google 広告アカウントの作成時に生成された乱数は、新しい Merchant Center アカウントの名前にも使用されます。
SolutionRunner.java
Account newMcAccount = new Account()
.setName(String.format("Merchant Center Account Created by Run %d", run))
.setAdwordsLinks(
ImmutableList.of(
new AccountAdwordsLink()
.setAdwordsId(BigInteger.valueOf(adWordsId))
.setStatus("active")));
このステップの説明で説明したように、新しい MCC アカウントの AdWords ID はすでに取得しているため、その ID を新しいサブアカウントの AdwordsLinks のリストに追加できます。新しいサブアカウントが作成されると、このリンクが自動的にリクエストされ、AdWords API で利用できるようになります。
新しいサブアカウントを作成する
Content API では、セッション オブジェクトの accounts() メソッドを呼び出して Accounts サービスにアクセスし、オペレーション オブジェクトを設定する代わりに insert() メソッドを直接呼び出します。このメソッドには、新しいサブアカウントを作成するマルチクライアント アカウントの ID と、必要な設定を含む Account オブジェクトの 2 つの引数を指定します。
SolutionRunner.java
newMcAccount = contentApiSession.accounts().insert(mcaId, newMcAccount).execute();
System.out.printf("Created new Merchant Center account %s%n", newMcAccount.getId());
insert() メソッドは、新しいサブアカウントの設定を含む Account オブジェクトを返します。返されたバージョンには、新しいサブアカウントの ID という重要な情報が含まれているため、元の Account オブジェクトを上書きします。ソリューションの出力にその値を出力します。これにより、ソリューションを実行して、新しいサブアカウントが Merchant Center に存在することを確認できます。
テストする
前回と同様に、ソリューションを実行してみてください。コマンドラインから Maven を使用している場合:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
問題がなければ、エラーは表示されず、新しい AdWords アカウントと新しい Merchant Center アカウントの両方の ID が表示されます。マルチクライアント アカウントの Merchant Center で、新しいサブアカウントを確認します。
7. AdWords アカウントからのリンクを承認します
最後のステップでは、新しい Merchant Center サブアカウントを作成し、同時に新しい AdWords アカウントへのリンクをリクエストしました。このステップでは、AdWords API を使用してリクエストされたリンクを承認し、プロセスを完了します。
CustomerService にアクセスする
前回と同様に、AdWordsServices クラスを使用して CustomerService のクライアントを取得します。ただし、クライアントを作成する前に、AdWords セッション オブジェクトを変更して、今後は MCC アカウントではなく新しい管理対象アカウントで操作されるようにします。結局のところ、Merchant Center アカウントがリクエストしたのは、MCC アカウントではなく、管理対象アカウントへのリンクです。
SolutionRunner.java
// TODO(acceptLink): Using the mutateServiceLinks method in CustomerService, accept the
// proposed link between the new AdWords account and the new Merchant Center account.
adWordsSession.setClientCustomerId(adWordsId.toString());
CustomerServiceInterface customerService =
adWordsServices.get(adWordsSession, CustomerServiceInterface.class);
リクエストされたリンクを指定する
新しい AdWords アカウントを作成するときと同様に、リンク設定を含む ServiceLink オブジェクトを作成し、目的のオペレーションを記述する ServiceLinkOperation オブジェクトを作成します。ここでは、保留中のサービスのリンクを MERCHANT_CENTER アカウントに移動し、SET で ACTIVE に移動します。serviceLinkId の設定には、Google 広告のサービスリンクの ID として使用される、作成した Merchant Center アカウントの ID を使用します。
SolutionRunner.java
ServiceLink serviceLink = new ServiceLink();
serviceLink.setServiceLinkId(newMcAccount.getId().longValue());
serviceLink.setLinkStatus(ServiceLinkLinkStatus.ACTIVE);
serviceLink.setServiceType(ServiceType.MERCHANT_CENTER);
ServiceLinkOperation op = new ServiceLinkOperation();
op.setOperator(Operator.SET);
op.setOperand(serviceLink);
リンクを承認する
最後に、CustomerService オブジェクトの mutateServiceLinks() メソッドを呼び出してオペレーションを実行します。前述のように、サービスリンク オペレーションの配列を受け取ります。今回は、メソッドが（変更されている可能性のある）サービスリンクのリストを直接返すため、そのリストをループしてソリューションの結果を出力します。もちろん、指定したオペレーションが 1 つしかないため、出力に表示されるリンクも 1 つだけです。
SolutionRunner.java
ServiceLink[] mutatedServiceLinks =
customerService.mutateServiceLinks(new ServiceLinkOperation[] {op});
for (ServiceLink mutatedServiceLink : mutatedServiceLinks) {
System.out.printf(
"Service link with service link ID %d, type '%s' updated to status: %s.%n",
mutatedServiceLink.getServiceLinkId(),
mutatedServiceLink.getServiceType(),
mutatedServiceLink.getLinkStatus());
}
テストする
前回と同様に、ソリューションを実行してみてください。コマンドラインから Maven を使用している場合:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
問題がなければ、エラーは表示されません。また、サービス リンクが有効になるように更新されたというメモも表示されます。AdWords と Merchant Center で、アカウントが実際にリンクされていることを再度確認します。
8. テーマのバリエーション
Codelab を完了しました。これで、完全に動作するソリューションが完成しました。次は、この Codelab で学習した API をさらに使用できるように、ソリューションを変更または拡張する方法の例を見てみましょう。
ボーナス ポイント: 既存の Merchant Center アカウントを更新して AdWords のリンクをリクエストする
この Codelab では、Merchant Center アカウントを作成するときに、その情報を使用してリンクをリクエストできるように、先に AdWords アカウントを作成しました。ただし、Merchant Center アカウントがすでに存在する場合は、その設定を更新する必要があります。コードを変更して、まず Merchant Center アカウントを作成してから、AdWords アカウントを作成した後で戻り、リンクをリクエストするように設定を更新してみてください。
追加のクレジット: AdWords アカウントと Merchant Center アカウントの情報を取得して、リンクが作成されたことを確認する
現在、このアプリでは、API 呼び出しでエラーが発生しなかった場合にのみ、成功と見なされます。サンプルを拡張して、新しい Merchant Center アカウントと AdWords アカウントのリンク情報を確認して、リンクが有効であることを確認します。
世界はあなたの思いのまま
他にも変更を加えたい場合は、ぜひお試しください。アイデアの参照コードが必要な場合は、Google ショッピングのサンプルと、Google 広告 Java クライアント ライブラリのソースの examples ディレクトリをご覧ください。