アカウントを管理する

このガイドではクライアント センター(MCC)アカウント、クライアント アカウント、テスト アカウントなどの AdWords アカウントを API を使って管理する方法を説明します。

このガイドはすでに AdWords の MCC アカウントとクライアント アカウントを使い慣れている方を対象としています。AdWords アカウントやアクセス権の基礎を復習したい場合は、AdWords ヘルプセンターの MCC アカウントアクセス権のページをご覧ください。

アカウントを作成、構成する

アカウントの作成やアカウント情報の取得、アカウント間のリンクの管理を行う場合は、AdWords API の CustomerServiceManagedCustomerService を使用します。アカウント ラベルの管理には AccountLabelService をご利用ください。

CustomerService

CustomerService はアカウントの情報を提供します。getCustomers() メソッドを使えば引数を指定することなく、customerIdcurrencyCodedateTimeZone などのフィールドを持つ Customer オブジェクトのリストを取得できます。CustomerService には mutate() メソッドもあり、autoTaggingEnabledconversionTrackingSetting フィールドなど顧客のさまざまな属性を更新できます。

v201605 以前のバージョンで clientCustomerId を指定しない場合、レスポンスには認証済みアカウントのエントリが 1 つだけ含まれます。MCC アカウントとして認証を受け、特定のアカウントの情報を取得する場合は、clientCustomerId を指定する必要があります(詳細は認証のセクションでご確認ください)。

v201607 以降のバージョンで clientCustomerId を指定しない場合、認証を受けたアカウントから直接アクセスできるアカウントが複数あれば、レスポンスに複数のエントリが含まれます。1 つのアカウントの結果のみ必要な場合は、リクエストで clientCustomerId を指定する必要があります。

レスポンスのサンプル:

<rval>
   <customerId>123456789</customerId>
   <currencyCode>USD</currencyCode>
   <dateTimeZone>America/New_York</dateTimeZone>
   <descriptiveName>myaccount</descriptiveName>
   <canManageClients>false</canManageClients>
</rval>

The Reference documentation contains a list of values for currencies and timezones.

ManagedCustomerService

ManagedCustomerService には get() メソッドと汎用セレクタも含まれています。CustomerService より多くのフィールドを選べるようになっているので、詳細を参照用ドキュメントで確認してください。

セレクタの条件に該当するアカウントのリストに加え、アカウント間の関係性を表す ManagedCustomerLink オブジェクトのリストも取得できます。

<rval>
 <totalNumEntries>3</totalNumEntries>
 <Page.Type>ManagedCustomerPage</Page.Type>
 <entries>
    <name>Account Created with MCS</name>
    <login/>
    <companyName/>
    <customerId>789</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>ZAR</currencyCode>
    <dateTimeZone>Pacific/Pago_Pago</dateTimeZone>
 </entries>
 <entries>
    <name>Adwords Test Manager Account</name>
    <login>my-manager-account@example.com</login>
    <companyName/>
    <customerId>123</customerId>
    <canManageClients>true</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <entries>
    <name>myaccount</name>
    <login>myaccount@example.com</login>
    <companyName/>
    <customerId>456</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>456</clientCustomerId>
 </links>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>789</clientCustomerId>
 </links>
</rval>

ManagedCustomerService は新しいアカウントの作成にも使用できます。これらの新しいアカウントは、有効なユーザー(MCC アカウントのユーザー)の管理下に置かれます。リクエストのサンプルは以下のとおりです。

<operations>
  <operator>ADD</operator>
  <operand>
    <name>Foo</name>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </operand>
</operations>

レスポンスのサンプル:

<rval>
  <value>
    <name>Foo</name>
    <customerId>9876543210</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </value>
</rval>

companyNamelogincanManageClients などのフィールドは読み取り専用で、新しいクライアント アカウントの作成時には無視されます。ManagedCustomerService は、作成済みのクライアント アカウントの更新には使用できません。

アカウントをリンクする

MCC アカウントとクライアント アカウントのリンクを設定すると、MCC アカウントで配下のクライアント アカウントに代わってリクエストを実行できるようになります。

ManagedCustomerService では、アカウント間のリンクを管理し、アカウント階層の管理を自動化できます。

  • ManagedCustomerService.mutateLink ではクライアント アカウントを招待する、クライアント アカウントとして招待の取り消し、拒否、承認を行う、MCC アカウントとクライアント アカウントのリンクを解除するといったことが可能です。
  • ManagedCustomerService.getPendingInvitations では、受諾も拒否もされていない招待をすべて確認できます。
  • ManagedCustomerService.mutateManager では、AdWords アカウントの管理者を別の MCC アカウントに変更できます。

MCC アカウントとクライアント アカウントをリンクする方法は以下のとおりです。

  1. MCC アカウントでクライアント アカウントに招待状を付与します。
  2. クライアント アカウントでその招待を受諾します

招待を付与する

MCC アカウントでは、クライアント アカウントや他の MCC アカウントを招待して管理できます。

その場合、MANAGER_ID は認証されている MCC アカウントか、階層内の子 MCC アカウントとなります。CLIENT_CID は、階層内の MCC アカウントによってまだ管理されていないクライアント アカウントか MCC アカウントにする必要があります。

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.PENDING);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.ADD);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

招待を付与するには、PENDING リンク ステータスを指定して ADD オペレーションを送信します。

保留中の招待を取得する

まだ反応がない招待のリストは、ManagedCustomerService.getPendingInvitations を使ってクライアント アカウントまたは MCC アカウントから取得できます。クライアント アカウントから受諾または拒否のレスポンスが返されるか、MCC アカウントで招待が取り消された場合、招待は保留状態ではなくなります。

ManagedCustomerService.get() の呼び出しでは ACTIVE のリンクのみ表示され、CANCELLEDREFUSEDINACTIVE のリンクは返されません。

以下の呼び出しでは、MCC アカウントの保留中の招待が返されます。

PendingInvitationSelector selector = new PendingInvitationSelector();
PendingInvitation[] invitations = managedCustomerService.getPendingInvitations(selector);

また、managerCustomerIds および clientCustomerIds フィールドにそれぞれ MCC アカウントとクライアント アカウントのお客様 ID を設定して、それらのアカウントの保留中の招待リストを取得することもできます。なお、clientCustomerIds を使ってリンクを確認するには、これが有効なアカウントの階層内で管理されている必要があります。この操作を行うユーザーがクライアント アカウントのユーザーだった場合は、そのアカウントで保留中となっている招待だけが返されます。

このリクエストに対しては ManagedCustomer レコードを含む PendingInvitations が返されます。 NamelogincompanyNamecustomerIdcanManageClients の各フィールドには、MCC とクライアントの両方のデータが入ります。

招待を取り消す

クライアント アカウントを管理下に置くための招待を送信した後で、その招待を取り消す場合は、そのリンクを管理できる MCC アカウントとして有効なアカウントを使い、SET オペレーションでリンクのステータスを CANCELLED に設定します。

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.CANCELLED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

クライアントが招待を拒否する

クライアント側でも、SET オペレーションを使ってリンクのステータスを REFUSED に設定することで招待を拒否できます。この操作を行うユーザーは、このリクエストの CLIENT_CID と一致するユーザーか、管理者権限を持つ所有者としてそれを管理するユーザーである必要があります。

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.REFUSED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

クライアントが招待に応じる

クライアントは SET オペレーションを使用してリンクのステータスを ACTIVE に設定することで招待に応じます。拒否する場合と同様、この操作を行うユーザーは、このリクエストの CLIENT_CID と一致するユーザーか、管理者権限を持つ所有者としてそれを管理するユーザーである必要があります。

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

クライアントまたはその MCC アカウントは、SET を使用して LinkStatusINACTIVE に設定することで、お互いのリンクを解除できます。

ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.INACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

この操作は MCC アカウントかクライアント アカウントで実行できます。

クライアント アカウントを移動する

MCC アカウント間で AdWords アカウントを移動するには、ManagedCustomerService.mutateManager を使用します。MCC アカウントとクライアント アカウントは、どちらも mutateManager() メソッドで簡単に移動できます。

MoveOperation op = new MoveOperation();
op.setOldManagerCustomerId(MANAGER_CID);
op.setOperator(Operator.SET);
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(NEW_MANAGER_CID);
op.setOperand(link);
managedCustomerService.mutateManager(new MoveOperation[]{op});

この場合、新しい MCC アカウントと古い MCC アカウントが両方とも操作の主体であるアカウントで管理されており、リンクのステータスが ACTIVE である必要があります。また、リンクの managerCustomerId として NEW_MANAGER_CID を使用し、MoveOperationoldManagerCustomerId では MANAGER_CID を指定します。

AccountLabelService

アカウント ラベルはアカウントの構成や管理に役立ちます。AccountLabelService では、アカウント単位でラベルを追加、更新、削除することが可能です。API を使用すると、下位の MCC アカウントのラベルも管理できます。

MCC アカウントの制限

MCC アカウントを使う際にはいくつかの制限事項があり、システム上の制限に関する参考ページで確認できます。このページにはシステム上のその他の制限もすべて記載されています。

AdWords アカウントがこうした制限に抵触することはほとんどありませんが、管理する AdWords アカウントが既になんらかの上限に達している場合は、該当のアカウントをリンクする前に問題を修正する必要があります。

また、処理のレート制限を超えないよう注意することも大切です。

認証

AdWords API に対する呼び出しでは、対象アカウントにアクセスするための承認済みの開発者トークンと、OAuth2 の認証情報が必要になります。

MCC アカウントとして認証を行う方法が最も簡単です。認証を済ませると、その MCC アカウントの配下にあるすべてのアカウントにアクセスできるようになります。認証は OAuth2 を使用して処理します。

開発者トークン

開発者トークンは、AdWords API のお申し込み時に自動的に生成されます。このトークンは、適用直後には承認待ちの状態になります。

While waiting for token approval, you'll be able to make calls against test accounts.トークンの承認後は、本番用の AdWords アカウントで呼び出しを実行できるようになります。

OAuth2 認証情報

指定した AdWords アカウントのデータの変更や取得を行うには、AdWords API に対する個々のリクエストが認証を受ける必要があります。対象のアカウントは、API の呼び出しで使用される OAuth2 認証情報によって決まります。

MCC アカウントの認証情報を使用した呼び出しの対象にできるのは、その MCC アカウントか、OAuth2 認証情報があるアカウントです。たとえば以下のような一般的な AdWords アカウントの階層があるとします。

開発者トークンは Root Manager Account 1 に属していても、別の階層内の MCC アカウントに属していてもよく、対象とするアカウントのクライアントのお客様 ID が指定されていれば、適用可能なアカウントには影響しません。

Client Account A に対する API 呼び出しを実行する場合は、Client Account A に関連付けられているログイン情報の OAuth2 認証情報を使用し、clientCustomerId リクエスト ヘッダーを Client A、Manager Account 2、または Root Manager Account 1 のお客様 ID に設定します。

このプロセスの場合、Manager Account 3 では Client Account C に対してのみ呼び出しを実行できます。管理対象ではない Client Account A と B には呼び出しを実行できません。Root Manager Account 1 では、階層内のどのアカウントに対しても呼び出しを実行できます。

MCC アカウントの認証情報を含む呼び出しでは、その MCC アカウントか、階層内でそのアカウントの配下にあるアカウントのみを対象に設定できます。そのためこの階層では、Client Account D に対して呼び出しを実行できるのは Root Manager Account 1 のみです。

MCC アカウントを使用する場合は、clientCustomerId をその MCC アカウントか、その子アカウントに設定します。

テスト アカウント

MCC アカウントとクライアント アカウントは階層の整理に便利ですが、本番環境に影響を与えることなく変更内容をテストしたい場合や、開発中に API 呼び出しをテストしたい場合は、テスト アカウントが適しています。

テスト アカウントを利用すると、新しい API 設定やアカウント設定を本番環境に実装する前にテストできます。

テスト アカウントは階層内に作成し、本番用アカウントと同じように整理できます。開発中に利用すると、以下のようなメリットがあります。

  • 承認済みの開発者トークンが不要なため、アプリケーションの審査、承認が完了する前の段階でも API をすぐにテストできます。
  • 広告は配信されず、本番用アカウントに影響が及ぶことがありません。
  • 通常のアカウントと同様に AdWords 管理画面でデータを表示して操作できます。

テスト用と本番用のアカウントが接点を持つことは避けなければならないため、既存の本番用 MCC アカウントの配下にテスト アカウントを作成することはできません。テスト アカウントを作成するには、最上位にテスト用の MCC アカウントを置いて、新しいアカウント階層を構築する必要があります。

テスト アカウントには AdWords 管理画面からアクセスできます。管理画面では赤いラベル付き(以下を参照)でデータが表示されます。

テスト アカウントには、レート制限を含め本番用アカウントと同じ制限事項が適用されます。

テスト アカウントを利用する

API リクエストをテスト アカウントに対して実行する前に、本番用(非テスト用)MCC アカウントと開発者トークンがあることをご確認ください。トークンは承認前のもので構いません。

テスト用クライアント アカウントを作成する前に、本番用 MCC アカウントを使用してテスト用 MCC アカウントを作成しておく必要があります。テスト用 MCC アカウントの配下に作成したクライアント アカウントは、すべて自動的にテスト アカウントとなります。

テスト アカウントを作成、使用する手順は以下のとおりです。

  1. まだ本番用 MCC アカウントがない、または本番用 MCC アカウントの開発者トークンがない場合:
    1. 本番用 MCC アカウントを作成します(例: production-manager@mycompany.example.com)。
    2. 本番用 MCC アカウントで開発者トークンをリクエストします。
  2. テスト用 MCC アカウントを作成します(例: test-manager@mycompany.example.com)。テスト アカウントを作成するには、まだ AdWords アカウントにリンクされていない Google アカウントが必要です。新しい Google アカウントは accounts.google.com で作成できます。
  3. 本番用 MCC アカウントの開発者トークンを使用してテスト用 MCC アカウントに対するリクエストを実行します。
  4. OAuth2 更新トークンをリクエストする際は、テスト用 MCC アカウントのユーザーとしてログインしてください(例: test-manager@mycompany.example.com)。

以下の表は、開発者トークンの承認状況と AdWords アカウントのタイプごとに、リクエストの送信が許可されるかどうかを示しています。

本番用の開発者トークンのステータス AdWords アカウントのタイプ 許可 / 不許可
承認待ち テスト 許可
承認待ち 非テスト 不許可
承認済み テスト 許可
承認済み 非テスト 許可

テスト アカウントで OAuth2 を使用する

OAuth2 を使用してテスト アカウントにアクセスするには、テスト用 MCC アカウントのユーザーがクライアント アプリケーションに許可を与える必要があります。そのため、リフレッシュ トークンをリクエストする際は、本番用 MCC アカウントではなく、テスト用 MCC アカウントのユーザーとしてログインしてください。

テスト用から本番用の MCC アカウントに切り替える際は、クライアント ライブラリを再設定して本番用 MCC アカウントのリフレッシュ トークンを使用します。

リクエストのヘッダー

テスト アカウントに対するすべてのリクエストは、本番環境でのリクエストと同じエンドポイントに送信する必要があります。

https://www.googleapis.com/auth/adwords/

SOAP リクエストと SOAP レスポンスのヘッダーは、本番用アカウントで返されるヘッダーと同じです。認証ヘッダーでは必ずテスト アカウントの認証情報を使用してください。

テスト アカウントのその他の特徴

テスト アカウントを使用する際は、以下の点にご注意ください。

  • TargetingIdeaServiceTrafficEstimatorService はテスト アカウントにダミーデータを返します。
  • テスト アカウントでは広告が配信されないため、指標データもありません。レポートでは表示回数や費用などの値がすべてゼロになります。
  • テスト アカウントでは関連するクリックが発生しないため、オフライン コンバージョン データのアップロードをテストすることはできません。
  • テスト アカウントでは DataService入札単価状況 を返しません。入札単価状況はアカウントから配信された広告に基づくためです。
  • テスト用 MCC アカウントの階層内で保有できるアカウントは 100 個までです。本番用 MCC アカウントでは最大数がこれよりもずっと多くなっています。

テスト アカウントの高度な利用方法

AdWords API の利用を申し込む際は、アプリケーションの一部の機能を実行して示すよう求められることがあります。レポートもその一つですが、この機能はテスト アカウントだけではエミュレートが困難な場合があります。

テスト アカウントでは広告が配信されないため、指標データが生成されません。構成レポートのダウンロードは可能ですが、表示回数がゼロの行しか表示されないため、セグメントも機能しません。

このような場合は、仮のデータを表示することをおすすめします。トークンの審査チームは、お客様のアプリケーションが適切に動作し、レポートのデータを表示できることを確認する必要があります。レポートの呼び出しを模倣する(レポートの呼び出しが成功したように見せかけ、仮のデータを入力してローカルに保存したファイルを使用する)ことで、API から実際にデータを取得しなくても、レポートにデータを追加することができます。

テスト用のレポートデータは、適切な形式で用意します。たとえば日付、キャンペーン名、キャンペーン ID、表示回数、クリック数、費用のデータを含むキャンペーンの掲載結果レポートを作成する場合は、以下のようなファイルを用意して取得します。

"CAMPAIGN_PERFORMANCE_REPORT (Mar 20, 2013-Mar 23, 2013)"
Day,Campaign,Campaign ID,Impressions,Clicks,Cost
20130320,Widgets,123,1211,19,14.92
20130320,Sprockets,456,300,4,2.92
20130321,Widgets,123,901,12,9.86
20130321,Sprockets,456,340,5,3.86
20130322,Widgets,123,1065,16,11.23
20130322,Sprockets,456,509,6,5.23
20130323,Widgets,123,1005,15,10.12
20130323,Sprockets,456,287,3,1.12

このようなファイルを作成してローカルに保存することで、アプリケーションによる API に対する呼び出しを模倣できます。レポートがリクエストされると、保管したファイルが返されて処理されます。実際の API 呼び出しは行われません。表示したいレポートごとにこのようなファイルを作成できます。

本番環境のデータを使ってテストを行う

リクエストで validateOnly ヘッダーを使用しており、承認済みの開発者トークンもある場合は、本番用アカウントのデータを読み取り専用形式で使用してテストを行うことができます。

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

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