Создание и связывание дочерних аккаунтов AdWords и Merchant Center

1. Введение

В этом практическом занятии вы изучите основы работы с Content API для покупок и AdWords API и создадите приложение, использующее оба этих инструмента. В частности, вы создадите приложение командной строки, которое будет создавать и связывать аккаунт AdWords и аккаунт Merchant Center.

Что вы узнаете

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

Что вам понадобится

• Аккаунт менеджера AdWords
• Многоклиентский аккаунт в Merchant Center
• Java 7+
• Мэйвен
• Пример кода
• Текстовый редактор (рекомендуется IDE, поддерживающая проекты Maven, например Eclipse или IntelliJ).

2. Настройка

Скачайте код

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

Скачать исходный код

Распакуйте загруженный zip-файл. В результате будет распакована корневая папка ( shopping-account-linking-master ), содержащая проект Maven со всеми необходимыми ресурсами. Особое внимание следует уделить следующим подкаталогам:

• src/main/java — это корневая директория исходного кода проекта Maven, содержащая шаблон кода, с которым вы можете работать.
• В src/main/java/solution находится готовое решение.

Установите необходимые пакеты и выполните сборку.

Если вы используете IDE, поддерживающую Maven, например Eclipse или IntelliJ , вы можете импортировать извлеченную папку как проект Maven, а затем скомпилировать проект обычным способом.

Если вы используете Maven из командной строки , вы можете выполнить следующую команду, чтобы получить необходимые пакеты и скомпилировать проект из корневой папки распакованного проекта ( shopping-account-linking-master ):

mvn compile

3. Настройка аутентификации

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

Настройте аутентификацию в AdWords API.

В этом практическом задании используется тот же способ загрузки учетных данных, что и в клиентской библиотеке, поэтому, если вы уже использовали клиентскую библиотеку Google Ads APIs для Java со своим аккаунтом администратора, то у вас все должно быть настроено. В противном случае, выполните шаги 1-3, чтобы начать работу с клиентской библиотекой Google Ads APIs для Java.

Настройте аутентификацию Content API.

Если у вас еще нет ключа учетной записи службы:

1. Перейдите в Центр обслуживания продавцов для вашей многоклиентской учетной записи и выберите Content API из дополнительного меню:
2. Выберите «Аутентификация» , затем нажмите синюю кнопку « +» :
3. После принятия условий использования Google Cloud Platform и Google API ваш браузер автоматически загрузит JSON-файл, содержащий ключ вашей новой учетной записи сервиса.

Теперь следуйте инструкциям по настройке аутентификации для примеров покупок с использованием сервисной учетной записи. То есть, копия ключа вашей сервисной учетной записи должна находиться по следующему пути в вашей домашней директории: shopping-samples/content/service-account.json . Вам не нужно настраивать конфигурацию примеров, если только вы не хотите попробовать примеры после завершения этого практического занятия!

Проверьте это

Теперь, когда у вас есть токены аутентификации в нужных местах, попробуйте запустить примеры. Если вы используете Maven в командной строке, выполните следующие команды:

mvn compile

Примечание: Если вы изменяете какие-либо файлы в src/main/resources , даже если вы не вносите никаких изменений в код (как на этом шаге), перекомпилируйте проект перед запуском примеров, чтобы скопировать измененные ресурсы в целевую папку.

mvn exec:java -Dexec.mainClass="SolutionRunner"

Если вы получаете сообщение об ошибке, указывающее на отсутствие предоставленных объектов сессии, значит, ваши токены аутентификации установлены и работают правильно! В противном случае, в сообщении об ошибке должно быть указано, какие учетные данные не сработали и какой файл нужно исправить.

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

4. Подключитесь к API.

Теперь, когда у вас есть действительные токены аутентификации для двух 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();

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

Мы также опускаем все необходимые операторы импорта для классов AdWords API и Content API, используемых в этих фрагментах кода. Если вы не используете IDE, которая может автоматически добавлять необходимые импорты, пожалуйста, проверьте код в пакете solution на наличие необходимых импортов.

Задавать имя приложения не обязательно, но здесь показано, как установить любые необходимые параметры с помощью объекта ShoppingContent.Builder перед вызовом метода build() .

Создайте объект сессии API AdWords.

Аналогично, существует класс AdWordsSession.Builder для создания объектов AdWordsSession . Главное отличие здесь в том, что вместо установки параметров конфигурации непосредственно в конструкторе мы будем использовать метод fromFile() для их загрузки из файла ads.properties который мы настроили на предыдущем шаге.

SolutionRunner.java

// TODO(sessions): Create a AdWordsSession object using AdWordsSession.Builder.
adWordsSession =
    new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(adwordsOAuth2Credential)
        .build();

Проверьте это

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

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

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

5. Создайте новый управляемый аккаунт AdWords.

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

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

Получите доступ к ManagedCustomerService

В API AdWords доступ к различным доступным сервисам осуществляется путем получения экземпляра класса AdWordsServices с помощью статического метода getInstance() . Используя этот экземпляр, мы можем затем создавать клиентов для этих сервисов с помощью метода get() , который принимает два аргумента: сессию, для которой нужно создать клиента, и интерфейс для нужного сервиса.

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 , который позволяет нам управлять «клиентами» (аккаунтами) AdWords из заданного аккаунта менеджера.

Укажите новые параметры учетной записи.

Сначала мы создадим объект ManagedCustomer , который будет содержать настройки для нашей новой учетной записи. Для этого практического занятия мы создадим тестовую учетную запись, установив валюту в долларах США и часовой пояс, совпадающий с западным побережьем США.

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

Мы также создаём случайное число, которое включаем в название аккаунта. Это необходимо для того, чтобы сопоставить аккаунт AdWords, который мы создадим здесь, с аккаунтом Merchant Center, который мы создадим позже, чтобы мы могли визуально проверить их после завершения работы над решением и убедиться, что связь между ними действительно существует.

Создайте новую управляемую учетную запись.

Для фактического создания новой учетной записи мы будем использовать ManagedCustomerOperation для указания операции ADD :

SolutionRunner.java

ManagedCustomerOperation operation = new ManagedCustomerOperation();
operation.setOperand(newAdWordsAccount);
operation.setOperator(Operator.ADD);

Затем мы выполним операцию с помощью метода mutate() ` объекта ` ManagedCustomerService . Этот метод принимает массив операций для выполнения, но здесь нам нужно выполнить только одну операцию. Результатом метода mutate() ` является значение, содержащее список объектов ManagedCustomer ; в данном случае это будет список, содержащий одного клиента — новую учетную запись, которую мы создали. Мы получим идентификатор этой новой учетной записи для дальнейшего использования, а также распечатаем его, чтобы он отображался в выходных данных нашего решения.

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, который мы создали. Проверьте сайт AdWords в своем личном кабинете, и вы также должны увидеть там новый аккаунт!

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

6. Создайте новый субсчет в Merchant Center.

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

Укажите параметры для нового субсчета.

В отличие от API AdWords, сеттеры класса модели Account возвращают объект, поэтому мы можем объединять вызовы к ним в цепочку для нового объекта Account . Мы также будем использовать случайное число, сгенерированное при создании аккаунта AdWords, в имени нового аккаунта 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")));

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

Создайте новый субсчет.

В Content API мы вызываем метод accounts() объекта сессии для доступа к службе Accounts , а затем напрямую вызываем метод insert() вместо создания объекта операции. Этот метод принимает два аргумента: идентификатор многоклиентской учетной записи, под которой нужно создать новую дочернюю учетную запись, и объект Account , содержащий необходимые настройки:

SolutionRunner.java

newMcAccount = contentApiSession.accounts().insert(mcaId, newMcAccount).execute();

System.out.printf("Created new Merchant Center account %s%n", newMcAccount.getId());

Метод insert() возвращает объект Account , содержащий настройки для нового субсчета. Мы перезаписываем исходный объект Account , поскольку возвращаемая версия содержит важную информацию: идентификатор нового субсчета. Мы выводим его в выходных данных нашего решения, чтобы затем запустить его и убедиться, что новый субсчет существует в Merchant Center.

Проверьте это

Как и прежде, попробуйте запустить решение. Если вы используете Maven из командной строки:

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

Если все пройдет успешно, ошибок по-прежнему не должно быть, и на этот раз мы увидим идентификаторы как нового аккаунта AdWords, так и нового аккаунта Merchant Center. Проверьте Merchant Center для вашего многоклиентского аккаунта, чтобы увидеть там новый субаккаунт.

Примечание: Как и в случае с AdWords, каждый запуск решения теперь будет создавать новые учетные записи в Merchant Center. После завершения работы решения вы можете удалить все созданные суб-аккаунты через Merchant Center .

7. Примите ссылку из аккаунта AdWords.

На последнем этапе мы создали новый суб-аккаунт Merchant Center, одновременно запросив привязку к нашему новому аккаунту AdWords. На этом этапе мы завершим процесс, используя API AdWords для принятия запрошенной привязки.

Обратитесь в службу поддержки клиентов.

Как и прежде, мы будем использовать класс AdWordsServices для получения клиента для CustomerService . Однако, прежде чем создавать клиента, мы сначала изменим наш объект сессии AdWords, чтобы в дальнейшем он работал с новым управляемым аккаунтом, а не с аккаунтом менеджера. В конце концов, аккаунт Merchant Center запросил ссылку на управляемый аккаунт, а не на аккаунт менеджера.

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 мы будем использовать идентификатор только что созданного аккаунта Merchant Center, поскольку он используется в качестве идентификатора сервисной ссылки в AdWords.

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

Примите ссылку

Наконец, мы вызовем метод ` mutateServiceLinks() ` объекта `CustomerService` для выполнения операции. Как и прежде, он принимает массив операций со ссылками на сервисы. На этот раз метод возвращает список (возможно, измененных) ссылок на сервисы напрямую, поэтому мы просто выведем результат нашего решения, пройдясь циклом по этому списку. Конечно, поскольку мы указали только одну операцию, вы ожидаете увидеть в выводе только одну ссылку.

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. Вариации на тему

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

Дополнительное задание: Обновите существующий аккаунт Merchant Center, чтобы запросить ссылку на AdWords.

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

Примечание: Вам следует использовать либо метод Accounts.update , либо метод Accounts.patch . Попробуйте оба варианта, чтобы понять разницу!

Важно : новая учетная запись Merchant Center может быть недоступна сразу после вызова метода Accounts.insert . До тех пор, пока новая учетная запись не станет доступна, при попытках доступа или изменения учетной записи вы будете получать ошибку HTTP 401. В примерах Shopping есть пример использования экспоненциальной задержки для повторной попытки выполнения методов в AccountWorkflow.java , который использует метод retryFailures из BaseWorkflowSample.java .

Дополнительное задание: Проверьте создание ссылки, получив информацию об учетных записях AdWords и Merchant Center.

В настоящее время приложение рассматривает отсутствие ошибок при вызовах API как признак успеха. Попробуйте расширить пример, чтобы проверить информацию о связи для новых аккаунтов Merchant Center и Adwords и убедиться, что связь действительно активна.

Примечание: со стороны Content API вам следует обратиться к методу Accounts.get . Со стороны AdWords вам следует использовать метод getServiceLinks объекта CustomerServiceInterface .

Весь мир у ваших ног.

Если вы придумаете другие изменения, которые можно внести, попробуйте их! Если вам нужен справочный код для ваших идей, ознакомьтесь с примерами Google Shopping и каталогом examples в исходном коде клиентской библиотеки Google Ads Java .