Управление аккаунтами

В этой статье объясняется, как работать с аккаунтами AdWords (управляющими, клиентскими и тестовыми) через API.

Это руководство предназначено для пользователей, имеющих представление об управляющих и клиентских аккаунтах AdWords. Если вам нужно освежить свои знания об аккаунтах AdWords и уровнях доступа, изучите соответствующие статьи в Справочном центре AdWords.

Создание и организация аккаунтов

Для создания аккаунтов, получения информации о них и управления связями между ними предназначены службы CustomerService и ManagedCustomerService, а для работы с ярлыками аккаунтов – служба AccountLabelService.

Служба CustomerService

Служба CustomerService предоставляет информацию об аккаунтах. В ней реализован метод getCustomers(), который не принимает никаких аргументов и возвращает список объектов Customer с такими полями, как customerId, currencyCode и dateTimeZone. Служба CustomerService также содержит метод mutate(), который можно использовать для изменения различных атрибутов клиента, включая поля autoTaggingEnabled и conversionTrackingSetting.

В версии 201605 и более ранних при отсутствии clientCustomerId ответ будет содержать одну запись для аккаунта, прошедшего аутентификацию. Чтобы получить сведения о конкретном аккаунте, укажите clientCustomerId при аутентификации в управляющем аккаунте (подробнее читайте в разделе Аутентификация ниже).

Начиная с версии 201607, если не указано значение clientCustomerId, ответ будет содержать несколько записей, если через аккаунт, прошедший аутентификацию, можно получить доступ более чем к одному аккаунту. Если вам нужны результаты только по одному аккаунту, задайте 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 также используется для создания новых аккаунтов. Они будут присвоены действующему пользователю (представляющему управляющий аккаунт). Вот пример такого запроса:

<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>

Такие поля, как companyName, login и canManageClients, доступны только для чтения и при создании нового клиентского аккаунта клиента не учитываются. C помощью службы ManagedCustomerService можно обновить созданный клиентский аккаунт.

Установление связи между аккаунтами

Установление связи между управляющим и клиентским аккаунтами позволяет управляющему аккаунту выполнять запросы от имени клиентских аккаунтов.

Для управления связями между аккаунтами используется служба ManagedCustomerService. Она обеспечивает автоматическое управление иерархией аккаунта:

  • Метод ManagedCustomerService.mutateLink позволяет отправить, отозвать, отклонить или принять (со стороны клиентского аккаунта) приглашение, а также отменить связь между управляющим и клиентским аккаунтами.
  • Метод ManagedCustomerService.getPendingInvitations позволяет просмотреть все приглашения, которые ещё не были приняты или отклонены.
  • Метод ManagedCustomerService.mutateManager позволяет сменить управляющий аккаунт.

Чтобы установить связь между управляющим и клиентским аккаунтами, необходимо выполнить следующие действия:

  1. Управляющий аккаунт должен отправить приглашение клиентскому аккаунту.
  2. Клиент должен принять приглашение.

Отправка приглашений

Управляющий аккаунт может отправить приглашение клиентскому аккаунту или другому управляющему аккаунту.

В этом примере в качестве MANAGER_ID указывается управляющий аккаунт, в который выполнен вход, или дочерний управляющий аккаунт в иерархии. В качестве CLIENT_CID необходимо указать клиентский или управляющий аккаунт, который не находится под управлением другого аккаунта в вашей иерархии.

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});

Чтобы отправить приглашение, необходимо выполнить операцию ADD со статусом связи PENDING.

Метод getPendingInvitations

Метод ManagedCustomerService.getPendingInvitations позволяет извлечь приглашения, в ответ на которые не последовало никаких действий со стороны клиентского или управляющего аккаунта. Принятые, отклоненные и отозванные приглашения теряют статус ожидающих.

В вызове ManagedCustomerService.get() отображаются только связи со статусом ACTIVE. Связи со статусом CANCELLED, REFUSED и INACTIVE не возвращаются.

Приведенный ниже вызов возвращает все ожидающие приглашения для управляющего аккаунта.

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

Чтобы извлечь ожидающие приглашения для управляющих и клиентских аккаунтов, укажите нужные идентификаторы в полях managerCustomerIds и clientCustomerIds соответственно. Обратите внимание, что связи клиентов доступны только в том случае, если управление аккаунтами, указанными в поле clientCustomerIds, осуществляется на уровне иерархии действующего аккаунта. Если действующий пользователь имеет клиентский аккаунт, возвращаются ожидающие приглашения только для него.

Этот запрос возвращает объект PendingInvitations с записями ManagedCustomer. Для менеджера и клиента заполняются поля Name, login, companyName, customerId и canManageClients.

Отзыв приглашений

Чтобы отозвать приглашение на управление клиентским аккаунтом, необходимо присвоить связи статус CANCELLED в операции SET. При этом в качестве действующего аккаунта должен быть выбран управляющий аккаунт с правами на управление этой связью.

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});

Отклонение приглашения клиентом

Чтобы отклонить приглашение, клиент присваивает связи статус REFUSED в операции SET. Действующий пользователь должен являться владельцем и администратором аккаунта, заданного атрибутом 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});

Принятие приглашения клиентом

Чтобы принять приглашение, клиент присваивает связи статус ACTIVE в операции SET. Как и в случае с отклонением, действующий пользователь должен являться владельцем и администратором аккаунта, заданного атрибутом 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});

Чтобы отменить связь между аккаунтами, присвойте ей статус 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});

Это можно сделать как из управляющего, так и из клиентского аккаунта.

Передача клиентских аккаунтов

Метод ManagedCustomerService.mutateManager позволяет передать аккаунт AdWords другому менеджеру. С помощью метода 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});

Старый и новый менеджеры должны находиться под управлением действующего аккаунта. Присвойте связи статус ACTIVE. Идентификатор нового менеджера NEW_MANAGER_CID указывается в атрибуте managerCustomerId связи. Идентификатор старого менеджера MANAGER_CID задается в атрибуте oldManagerCustomerId операции MoveOperation.

Служба AccountLabelService

Ярлыки помогают организовать аккаунты и облегчают управление ими. С помощью службы AccountLabelService можно добавлять, обновлять и удалять ярлыки на уровне аккаунта. Используя API, вы также можете работать с ярлыками в аккаунтах подчиненных менеджеров.

Ограничения для управляющих аккаунтов

При работе с управляющими аккаунтами действует ряд ограничений. Они описаны на странице Системные ограничения, где также приведен полный список других ограничений.

Для аккаунтов AdWords эти ограничения превышаются редко. Однако если это произошло, прежде чем установить связь с таким аккаунтом, вам потребуется устранить выявленные нарушения.

Кроме того, важно не превышать ограничения на количество запросов.

Аутентификация

Для вызова AdWords API необходимы два компонента: одобренный токен разработчика и учетные данные, созданные в OAuth2.

Самый простой подход состоит в том, чтобы провести аутентификацию управляющего аккаунта. После этого вы получите доступ ко всем аккаунтам в этом управляющем аккаунте. Аутентификация осуществляется через OAuth2.

Токен разработчика

При регистрации пользователя AdWords API для вас автоматически создается токен разработчика. Как только вы зарегистрируетесь, ваш токен будет отправлен на рассмотрение.

While waiting for token approval, you'll be able to make calls against test accounts. Как только токен будет одобрен, вы сможете обращаться к рабочим аккаунтам AdWords через API.

Учетные данные OAuth2

Для каждого запроса AdWords API необходима авторизация на внесение изменений в аккаунт AdWords или получение данных из него. От учетных данных OAuth2, указанных в вызове API, зависит то, к каким аккаунтам может обращаться запрос.

Вызовы с использованием учетных данных управляющего аккаунта можно адресовать управляющему аккаунту или любому аккаунту, учетные данные которого у вас есть. Например, рассмотрим типичную иерархию аккаунта AdWords.

Ваш токен разработчика может относиться к корневому управляющему аккаунту 1 или даже к управляющему аккаунту в другой иерархии. Это не влияет на то, к каким аккаунтам вы можете обращаться. От вас лишь требуется предоставить идентификатор клиента для целевого клиентского аккаунта.

Чтобы обратиться к клиентскому аккаунту A через API, необходимо использовать учетные данные OAuth2 для логина, связанного с этим клиентским аккаунтом, и указать в заголовке запроса clientCustomerId идентификатор клиента A, управляющего аккаунта 2 или корневого управляющего аккаунта 1.

При такой структуре управляющий аккаунт 3 может обращаться только к клиентскому аккаунту C. Он не может обращаться к клиентским аккаунтам A и B, поскольку не управляет ими. Корневой управляющий аккаунт 1 может обращаться к любому аккаунту в иерархии.

Вызовы с использованием учетных данных управляющего аккаунта можно адресовать только тем аккаунтам, которые ему подчинены. Таким образом, в этой иерархии только корневой управляющий аккаунт 1 может обращаться к клиентскому аккаунту D.

Если вы используете один из управляющих аккаунтов, укажите в заголовке clientCustomerId этот управляющий аккаунт или один из его подчиненных аккаунтов.

Тестовые аккаунты

Управляющие и клиентские аккаунты подходят для организации иерархии, но как насчет тестирования экспериментальных изменений или вызовов API без оказания влияния на рабочую среду? Именно для этого и предназначены тестовые аккаунты.

Тестовые аккаунты позволяют испытывать новые реализации API и конфигурации аккаунта перед внесением изменений в рабочую среду.

Тестовые аккаунты можно добавить в иерархию и организовать точно так же, как и рабочие аккаунты. При этом они обеспечивают дополнительные преимущества на этапе активной разработки. В частности, тестовые аккаунты:

  • Не требуют использования одобренного токена разработчика, поэтому можно сразу же начать эксперименты с API, не дожидаясь рассмотрения вашего приложения.
  • Не показывают объявления и не взаимодействуют с рабочими аккаунтами.
  • Могут просматриваться и настраиваться через веб-интерфейс AdWords, как и обычные аккаунты.

Поскольку тестовые аккаунты никак не взаимодействуют с рабочими, их нельзя связать с рабочими управляющими аккаунтами. Для работы с тестовыми аккаунтами нужно создать новую иерархию аккаунтов, где в качестве корневого будет использоваться тестовый управляющий аккаунт.

Тестовые аккаунты доступны через веб-интерфейс AdWords и появляются с красной пометкой (см. ниже).

К тестовым аккаунтам применяются те же ограничения, что и к рабочим.

Начало работы с тестовыми аккаунтами

Прежде чем отправлять запросы API в тестовый аккаунт, убедитесь, что у вас есть рабочий (не тестовый) управляющий аккаунт и токен разработчика, даже если этот токен все ещё находится на рассмотрении.

При использовании рабочего управляющего аккаунта необходимо сначала создать тестовый управляющий аккаунт, прежде чем создавать тестовые клиентские аккаунты. Все клиентские аккаунты, созданные в тестовом управляющем аккаунте, автоматически становятся тестовыми.

Чтобы создать и использовать тестовый аккаунт, выполните следующие действия:

  1. Если у вас ещё нет рабочего управляющего аккаунта и/или токена разработчика рабочего управляющего аккаунта:
    1. Создайте рабочий управляющий аккаунт (например, production-manager@mycompany.example.comproduction-manager@mycompany.example.com).
    2. Запросите токен разработчика в рабочем управляющем аккаунте.
  2. Создайте тестовый управляющий аккаунт (например, test-manager@mycompany.example.com). Для этого необходимо иметь существующий аккаунт Google, не связанный с аккаунтом AdWords. Новый аккаунт Google можно создать на странице accounts.google.com.
  3. При обращении к тестовому управляющему аккаунту необходимо использовать токен разработчика рабочего управляющего аккаунта.
  4. Запрашивая токен обновления OAuth2, убедитесь, что вы выполнили вход как пользователь тестового управляющего аккаунта (например, test-manager@mycompany.example.com).

В таблице ниже представлены разрешенные взаимодействия между различными типами аккаунтов и токенами разработчика с учетом статуса рассмотрения:

Статус рабочего токена разработчика Тип аккаунта AdWords Разрешено
На рассмотрении Тестовый Да
На рассмотрении Не тестовый Нет
Одобрено Тестовый Да
Одобрено Не тестовый Да

Использование OAuth2 с тестовыми аккаунтами

Чтобы обеспечить доступ к тестовому аккаунту с использованием OAuth2, тестовый управляющий аккаунт должен предоставить соответствующие разрешения клиентскому приложению. Таким образом, запрашивая токен обновления, убедитесь, что вы вошли в тестовый управляющий аккаунт, а не в рабочий управляющий аккаунт.

Когда нужно будет перейти от тестового управляющего аккаунта к рабочему управляющему аккаунту, просто перенастройте клиентскую библиотеку на использование токена обновления рабочего управляющего аккаунта.

Заголовки запроса

Все запросы к тестовым аккаунтам должны направляться на ту же конечную точку, что и рабочие:

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

В тестовых и рабочих аккаунтах используются одинаковые SOAP-заголовки запросов и ответов. Для заголовков авторизации следует использовать учетные данные тестового аккаунта.

Дополнительные свойства тестовых аккаунтов

При работе с тестовыми аккаунтами важно помнить следующее:

  • Службы TargetingIdeaService и TrafficEstimatorService возвращают в тестовые аккаунты фиктивные данные.
  • Поскольку показ объявлений не осуществляется, в тестовых аккаунтах нет показателей. Это влияет на отчеты: количество показов, расходы и другие значения будут нулевыми.
  • Тестовые аккаунты не имеют связанных кликов, поэтому их нельзя использовать для тестирования загрузки офлайн-конверсий.
  • Служба DataService не возвращает распределение ставок для тестовых аккаунтов, поскольку оно основано на показе объявлений из аккаунта.
  • В иерархии тестового управляющего аккаунта может быть не более 100 аккаунтов. Для рабочих аккаунтов этот предел гораздо выше.

Разработка с использованием тестовых аккаунтов

При регистрации для доступа к AdWords API вам может быть потребоваться продемонстрировать некоторые функции вашего приложения. Одной из них может быть создание отчетов. Эту функцию сложно эмулировать, работая лишь с тестовыми аккаунтами.

Поскольку тестовые аккаунты не показывают объявления, в них отсутствуют показатели. Тем не менее вы можете скачать структурные отчеты, однако они будут содержать нулевое количество показов. Таким образом, сегменты работать не будут.

Для решения этой проблемы мы предлагаем показывать фиктивные данные. Специалистам по рассмотрению токенов необходимо убедиться, что ваше объявление может взаимодействовать с данными в отчетах и выводить их. Выполняя фиктивное обращение к отчету (т. е. предполагая, что обращение к отчету произошло успешно и что используется локальный файл с фиктивными отчетными данными), вы можете добавить данные из него, не получая их через API.

Убедитесь, что тестовые отчетные данные имеют правильный формат. Например, отчет по эффективности кампаний, содержащий дату, название кампании, идентификатор кампании, количество кликов, количество показов и расходы, должен выглядеть приблизительно так:

"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 и у вас есть одобренный токен разработчика.

Оставить отзыв о...

Текущей странице
Нужна помощь? Обратитесь в службу поддержки.