Tworzenie i łączenie subkont AdWords i Merchant Center

1. Wprowadzenie

Z tego ćwiczenia dowiesz się, jak korzystać z interfejsu Content API for Shopping i interfejsu AdWords API oraz jak utworzyć aplikację, która używa obu tych interfejsów. W szczególności utworzysz aplikację wiersza poleceń, która utworzy i połączy konto Google Ads oraz konto Merchant Center.

Czego się nauczysz

• Jak tworzyć konta Google Ads zarządzane przez konto menedżera.
• Jak tworzyć konta Merchant Center zarządzane przez multikonto klientów.
• Jak wysłać prośbę o połączenie konta Merchant Center z kontem Google Ads.
• Jak zaakceptować oczekujące połączenie z Merchant Center na koncie Google Ads.

Czego potrzebujesz

• Konto menedżera Google Ads
• Multikonto klientów w Merchant Center
• Java 7 lub nowsza
• Maven
• Przykładowy kod
• Edytor tekstu (zalecamy IDE, które obsługuje projekty Maven, np. Eclipse lub IntelliJ)

2. Przygotowania

Pobieranie kodu

Kliknij ten link, aby pobrać cały kod na potrzeby tego ćwiczenia:

Pobierz kod źródłowy

Rozpakuj pobrany plik ZIP. Spowoduje to rozpakowanie folderu głównego (shopping-account-linking-master), który zawiera projekt Maven oraz wszystkie potrzebne zasoby. Szczególną uwagę zwróć na te podkatalogi:

• src/main/java to katalog główny projektu Maven, który zawiera szkielet kodu, w którym będziesz pracować.
• src/main/java/solution zawiera gotowe rozwiązanie.

Instalowanie wymaganych pakietów i tworzenie kompilacji

Jeśli używasz IDE obsługującego Maven, np. Eclipse lub IntelliJ, możesz zaimportować wyodrębniony folder jako projekt Maven, a następnie skompilować projekt w normalny sposób.

Jeśli używasz Maven z poziomu wiersza poleceń, możesz uruchomić to polecenie, aby pobrać niezbędne pakiety i skompilować projekt z folderu głównego rozpakowanego projektu (shopping-account-linking-master):

mvn compile

3. Konfigurowanie uwierzytelniania

W tym kroku nie będziemy pisać kodu, ale skonfigurujemy pliki zawierające odpowiednie tokeny uwierzytelniania dla interfejsu AdWords API i interfejsu Content API for Shopping.

Konfigurowanie uwierzytelniania interfejsu AdWords API

To ćwiczenie korzysta z tego samego sposobu wczytywania danych logowania co biblioteka klienta, więc jeśli masz już skonfigurowaną bibliotekę klienta interfejsów Google Ads API dla języka Java na koncie menedżera, wszystko powinno być gotowe. W przeciwnym razie wykonaj kroki 1–3, aby rozpocząć korzystanie z biblioteki klienta interfejsów Google Ads API dla języka Java.

Konfigurowanie uwierzytelniania interfejsu Content API

Jeśli nie masz jeszcze klucza konta usługi:

1. Otwórz Merchant Center na swoim multikoncie klientów i w rozszerzonym menu wybierz Content API:
2. Kliknij Uwierzytelnianie, a potem niebieski przycisk +:
3. Po zaakceptowaniu Warunków korzystania z Google Cloud Platform i interfejsów API Google Twoja przeglądarka automatycznie pobierze plik JSON zawierający nowy klucz konta usługi.

Teraz postępuj zgodnie z instrukcjami dotyczącymi konfigurowania uwierzytelniania na potrzeby przykładów Shopping za pomocą konta usługi. Kopia klucza konta usługi powinna znajdować się w tej ścieżce w katalogu domowym: shopping-samples/content/service-account.json. Nie musisz konfigurować przykładów, chyba że chcesz je wypróbować po ukończeniu tego ćwiczenia.

Testowanie

Gdy tokeny uwierzytelniania będą już w odpowiednich miejscach, spróbuj uruchomić przykłady. Jeśli używasz Maven z poziomu wiersza poleceń, uruchom te polecenia:

mvn compile

Uwaga: jeśli zmienisz którykolwiek z plików w src/main/resources, nawet jeśli nie wprowadzisz żadnych zmian w kodzie (jak w tym kroku), przed uruchomieniem przykładów ponownie skompiluj projekt, aby skopiować zmienione zasoby do katalogu docelowego.

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

Jeśli pojawi się komunikat o błędzie informujący, że nie podano obiektów sesji, tokeny uwierzytelniania są prawidłowe i działają poprawnie. W przeciwnym razie komunikat o błędzie powinien informować, które dane logowania nie działają i który plik należy poprawić.

Ważne: udostępniona przez nas platforma zakłada, że konto usługi Content API jest wymienione tylko jako użytkownik na Twoim multikoncie klientów. Jeśli pojawi się błąd informujący, że Twoje konto usługi ma dostęp do więcej niż 1 konta, wykonaj powyższe czynności, aby uzyskać klucz konta usługi przeznaczony specjalnie dla Twojego multikonta klientów.

4. Łączenie z interfejsami API

Gdy masz już prawidłowe tokeny uwierzytelniania dla 2 interfejsów API, których będziemy używać, zacznijmy wypełniać kod. Zaczniemy od utworzenia obiektów sesji za pomocą tokenów uwierzytelniania. W kolejnych krokach będziemy uzyskiwać dostęp do różnych usług i metod udostępnianych przez każdy interfejs API za pomocą tych obiektów sesji.

Tworzenie obiektu sesji Content API

Aby utworzyć sesję Content API, utworzymy obiekt ShoppingContent.Builder, a następnie użyjemy go do utworzenia odpowiedniego obiektu ShoppingContent. Na szczęście wszystko, czego potrzebujemy do utworzenia tego pierwszego, jest już dostępne w szkielecie kodu, więc wystarczy to połączyć w ten sposób:

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

Uwaga: początkowe komentarze w tym i kolejnych przykładach kodu są już dostępne w szkielecie kodu. Poszukaj ich, aby zobaczyć, gdzie należy dodać te wiersze.

Pomijamy też wszystkie potrzebne instrukcje importowania klas interfejsu AdWords API i interfejsu Content API, których używamy w tych fragmentach. Jeśli nie używasz IDE, które może automatycznie dodawać prawidłowe importy, sprawdź kod w pakiecie solution, aby znaleźć potrzebne importy.

Ustawienie nazwy aplikacji nie jest konieczne, ale pokazuje, jak ustawić dowolne opcje za pomocą obiektu ShoppingContent.Builder przed wywołaniem metody build().

Tworzenie obiektu sesji interfejsu AdWords API

Podobnie istnieje klasa AdWordsSession.Builder do tworzenia obiektów AdWordsSession. Główna różnica polega na tym, że zamiast ustawiać opcje konfiguracji bezpośrednio w konstruktorze, użyjemy metody fromFile() do wczytania ich z pliku ads.properties, który skonfigurowaliśmy w poprzednim kroku.

SolutionRunner.java

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

Testowanie

Jeśli uruchamiasz projekt Maven z poziomu wiersza poleceń, użyj tych samych poleceń co w poprzedniej sekcji, aby go ponownie utworzyć i uruchomić:

mvn compile

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

Tym razem nie powinny się pojawić żadne błędy, ale też nie zobaczysz żadnych interesujących danych wyjściowych. Dodamy je, gdy będziemy wywoływać interfejsy API, aby utworzyć i połączyć nowe konta.

5. Tworzenie nowego zarządzanego konta Google Ads

Gdy utworzymy już obiekty sesji interfejsu API, utworzymy konta, które chcemy połączyć. Zaczniemy od Google Ads i utworzymy konto testowe na naszym koncie menedżera.

Uwaga: wszystkie fragmenty kodu w tej sekcji są dodawane w tym samym miejscu w szkielecie kodu w podanej kolejności. Z tego powodu w pierwszym fragmencie pokażemy tylko komentarz (// TODO...), który wskazuje, gdzie należy je umieścić. Jeśli więc w tym i kolejnych krokach zobaczysz fragmenty kodu bez komentarza wprowadzającego, umieść je bezpośrednio po poprzednim fragmencie.

Uzyskiwanie dostępu do ManagedCustomerService

W interfejsie AdWords API uzyskujemy dostęp do różnych dostępnych usług, najpierw pobierając instancję klasy AdWordsServices za pomocą statycznej metody getInstance(). Za pomocą tej instancji możemy następnie tworzyć klientów dla tych usług za pomocą metody get(), która przyjmuje 2 argumenty: sesję, dla której ma zostać utworzony klient, oraz interfejs żądanej usługi.

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

W tym przypadku uzyskujemy dostęp do ManagedCustomerService, która umożliwia zarządzanie „klientami” (kontami) Google Ads z poziomu danego konta menedżera.

Określanie ustawień nowego konta

Najpierw utworzymy obiekt ManagedCustomer, który zawiera ustawienia nowego konta. Na potrzeby tego ćwiczenia utworzymy konto testowe, ustawiając jego walutę na USD, a strefę czasową na taką samą jak na zachodnim wybrzeżu USA.

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

Tworzymy też liczbę losową, którą uwzględniamy w nazwie konta. Dzięki temu możemy dopasować konto Google Ads, które utworzymy w tym kroku, do konta Merchant Center, które utworzymy później. Będziemy mogli je wizualnie sprawdzić po ukończeniu rozwiązania i upewnić się, że zostały połączone.

Tworzenie nowego konta zarządzanego

Aby utworzyć nowe konto, użyjemy ManagedCustomerOperation, aby określić operację ADD:

SolutionRunner.java

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

Następnie wykonamy operację za pomocą metody mutate() obiektu ManagedCustomerService. Ta metoda przyjmuje tablicę operacji do wykonania, ale w tym przypadku chcemy wykonać tylko jedną operację. Wynikiem metody mutate() jest wartość zawierająca listę ManagedCustomers. W tym przypadku będzie to lista zawierająca 1 klienta – nowe utworzone przez nas konto. Pobierzemy identyfikator tego nowego konta, aby użyć go w przyszłości, a także go wydrukujemy, aby był widoczny w danych wyjściowych naszego rozwiązania.

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

Testowanie

Jak poprzednio, spróbuj uruchomić rozwiązanie. Jeśli używasz Maven z poziomu wiersza poleceń:

mvn compile

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

Jeśli wszystko pójdzie dobrze, nadal nie powinny się pojawić żadne błędy, a tym razem zobaczymy identyfikator nowego konta Google Ads, które utworzyliśmy. Sprawdź witrynę AdWords na swoim koncie menedżera. Powinno się tam wyświetlać nowe konto.

Uwaga: od tego momentu każde uruchomienie rozwiązania będzie generować nowe konta. Po zakończeniu uruchamiania rozwiązania możesz anulować utworzone konta Google Ads w witrynie AdWords. Nasz schemat nazewnictwa tych kont ułatwia sprawdzenie, które z nich zostały utworzone przez nasz kod.

6. Tworzenie nowego subkonta Merchant Center

W tym kroku utworzymy subkonto Merchant Center, które połączymy z kontem Google Ads utworzonym w poprzednim kroku. Zamiast wysyłać oddzielną prośbę o połączenie po utworzeniu subkonta, możemy wysłać prośbę o połączenie podczas tworzenia, ponieważ mamy już identyfikator odpowiedniego konta Google Ads.

Określanie ustawień nowego subkonta

W przeciwieństwie do interfejsu AdWords API, metody ustawiające klasy modelu Account zwracają obiekt, dzięki czemu możemy łączyć wywołania tych metod w nowym obiekcie Account. W nazwie nowego konta Merchant Center użyjemy też liczby losowej wygenerowanej podczas tworzenia konta Google Ads.

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

Jak wspomnieliśmy we wstępie do tego kroku, ponieważ mamy już identyfikator Google Ads nowego konta zarządzanego, możemy teraz dodać ten identyfikator do listy AdwordsLinks nowego subkonta. Gdy utworzymy nowe subkonto, to połączenie zostanie automatycznie wysłane i będzie dostępne w interfejsie AdWords API.

Tworzenie nowego subkonta

W interfejsie Content API wywołujemy metodę accounts() obiektu sesji, aby uzyskać dostęp do usługi Accounts, a następnie wywołujemy bezpośrednio metodę insert() zamiast konfigurować obiekt operacji. Ta metoda przyjmuje 2 argumenty: identyfikator multikonta klientów, na którym ma zostać utworzone nowe subkonto, oraz obiekt Account zawierający żądane ustawienia:

SolutionRunner.java

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

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

Metoda insert() zwraca obiekt Account, który zawiera ustawienia nowego subkonta. Zastępujemy nasz pierwotny obiekt Account, ponieważ zwrócona wersja zawiera ważną informację – identyfikator nowego subkonta. Drukujemy go w danych wyjściowych naszego rozwiązania, abyśmy mogli uruchomić rozwiązanie, a następnie sprawdzić, czy nowe subkonto istnieje w Merchant Center.

Testowanie

Jak poprzednio, spróbuj uruchomić rozwiązanie. Jeśli używasz Maven z poziomu wiersza poleceń:

mvn compile

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

Jeśli wszystko pójdzie dobrze, nadal nie powinny się pojawić żadne błędy, a tym razem zobaczymy identyfikatory zarówno nowego konta Google Ads, jak i nowego konta Merchant Center. Sprawdź Merchant Center na swoim multikoncie klientów, aby zobaczyć tam nowe subkonto.

Uwaga: podobnie jak w przypadku Google Ads, każde uruchomienie rozwiązania będzie teraz generować nowe konta Merchant Center. Po zakończeniu uruchamiania rozwiązania możesz usunąć utworzone subkonta w Merchant Center.

7. Akceptowanie połączenia z konta Google Ads

W ostatnim kroku utworzyliśmy nowe subkonto Merchant Center, jednocześnie wysyłając prośbę o połączenie z naszym nowym kontem Google Ads. W tym kroku dokończymy proces, akceptując prośbę o połączenie za pomocą interfejsu AdWords API.

Uzyskiwanie dostępu do CustomerService

Jak poprzednio, użyjemy klasy AdWordsServices, aby uzyskać klienta dla CustomerService. Zanim jednak utworzymy klienta, najpierw zmienimy obiekt sesji Google Ads, aby w przyszłości używać nowego konta zarządzanego zamiast konta menedżera. Konto Merchant Center wysłało prośbę o połączenie z kontem zarządzanym , a nie z kontem menedżera.

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

Określanie żądanego połączenia

Podobnie jak w przypadku tworzenia nowego konta Google Ads, utworzymy obiekt ServiceLink, który zawiera ustawienia połączenia, a następnie obiekt ServiceLinkOperation, który opisuje żądaną operację. W tym przypadku chcemy zaakceptować oczekujące połączenie usługi z kontem MERCHANT_CENTER i SET je na ACTIVE. W przypadku ustawienia serviceLinkId użyjemy identyfikatora utworzonego przez nas konta Merchant Center, ponieważ jest on używany jako identyfikator połączenia usługi w Google Ads.

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

Akceptowanie połączenia

Na koniec wywołamy metodę mutateServiceLinks() obiektu CustomerService, aby wykonać operację. Jak poprzednio, przyjmuje ona tablicę operacji połączenia usługi. Tym razem metoda zwraca bezpośrednio listę (ewentualnie zmienionych) połączeń usługi, więc po prostu wyświetlimy wynik naszego rozwiązania, iterując po tej liście. Oczywiście, ponieważ określiliśmy tylko jedną operację, w danych wyjściowych powinien się pojawić tylko jeden link.

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

Testowanie

Jak poprzednio, spróbuj uruchomić rozwiązanie. Jeśli używasz Maven z poziomu wiersza poleceń:

mvn compile

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

Jeśli wszystko pójdzie dobrze, nadal nie powinny się pojawić żadne błędy, a tym razem zobaczymy też notatkę, że połączenie usługi zostało zaktualizowane i jest aktywne. Sprawdź AdWords i Merchant Center, aby upewnić się, że konta są teraz połączone.

8. Wariacje na temat

Gratulacje! Ćwiczenie ukończone. Gdy masz już w pełni działające rozwiązanie, przyjrzyjmy się kilku przykładom, jak możesz je zmodyfikować lub rozszerzyć, aby używać więcej interfejsów API, które zostały omówione w tym ćwiczeniu.

Dodatkowe zadanie: aktualizowanie istniejącego konta Merchant Center w celu wysłania prośby o połączenie z Google Ads

W tym ćwiczeniu najpierw utworzyliśmy konto Google Ads, aby móc użyć jego informacji do wysłania prośby o połączenie podczas tworzenia konta Merchant Center. Jeśli jednak konto Merchant Center już istnieje, musisz zaktualizować jego konfigurację. Spróbuj zmienić kod tak, aby najpierw utworzyć konto Merchant Center, a potem po utworzeniu konta Google Ads wrócić do niego i zaktualizować jego konfigurację, aby wysłać prośbę o połączenie.

Uwaga: użyj metody Accounts.update lub Accounts.patch. W rzeczywistości spróbuj użyć każdej z nich, aby zrozumieć różnicę.

Ważne: nowe konto Merchant Center może być niedostępne od razu po wywołaniu metody Accounts.insert. Do czasu, aż nowe konto będzie dostępne, próby uzyskania do niego dostępu lub jego modyfikacji będą powodować błąd HTTP 401. Przykłady Shopping zawierają przykład użycia wzrastającego czasu do ponowienia do ponawiania metod w AccountWorkflow.java, który używa metody retryFailures z BaseWorkflowSample.java.

Dodatkowe zadanie: weryfikowanie utworzenia połączenia przez pobranie informacji o koncie Google Ads i koncie Merchant Center

Obecnie aplikacja traktuje brak błędów w wywołaniach interfejsu API jako oznakę powodzenia. Spróbuj rozszerzyć przykład, aby sprawdzić informacje o połączeniu na nowych kontach Merchant Center i Google Ads oraz upewnić się, że połączenie jest aktywne.

Uwaga: po stronie interfejsu Content API użyj metody Accounts.get. Po stronie Google Ads użyj metody getServiceLinks obiektu CustomerServiceInterface.

Świat stoi przed Tobą otworem

Jeśli przyjdą Ci do głowy inne zmiany, które możesz wprowadzić, spróbuj je zastosować. Jeśli potrzebujesz kodu referencyjnego do swoich pomysłów, zapoznaj się z przykładami Google Shopping i katalogiem examples w źródle biblioteki klienta Google Ads dla języka Java.