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

1. Введение

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

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

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

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

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

2. Приступаем к настройке

Загрузите код

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

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

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

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

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

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

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

mvn compile

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

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

Настройте AdWords API для аутентификации

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

Настройте Content API для аутентификации

Если у вас еще нет ключа сервисного аккаунта:

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

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

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

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

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

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

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

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

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

Мир - твоя устрица

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