Tworzenie i łączenie subkont AdWords i Merchant Center

1. Wprowadzenie

W tym laboratorium programistycznym poznasz podstawy pracy z interfejsami Content API for Shopping i AdWords API oraz zbudujesz aplikację, która korzysta z obu tych interfejsów. W szczególności utworzysz aplikację wiersza poleceń, która utworzy i połączy konto AdWords z kontem Merchant Center.

Czego się nauczysz

• Jak tworzyć konta AdWords zarządzane przez konto menedżera.
• Jak tworzyć konta Merchant Center zarządzane przez multikonto klientów
• Jak poprosić o połączenie konta Merchant Center z kontem AdWords
• Jak zaakceptować oczekujące połączenie z Merchant Center na koncie AdWords.

Czego potrzebujesz

• konto menedżera AdWords,
• multikonto klientów w Merchant Center;
• Java 7 lub nowsza
• Maven
• Przykładowy kod
• edytor tekstu (zalecany jest IDE obsługujący projekty Maven, np. Eclipse lub IntelliJ);

2. Konfiguracja

Pobierz kod.

Aby pobrać cały kod tego ćwiczenia, kliknij ten link:

Pobierz kod źródłowy

Rozpakuj pobrany plik ZIP. Spowoduje to rozpakowanie folderu katalogu głównego (shopping-account-linking-master), który zawiera projekt Maven wraz ze wszystkimi potrzebnymi zasobami. Szczególnie ważne są te katalogi podrzędne:

• src/main/java to katalog główny projektu Maven, który zawiera szkielet kodu do pracy.
• src/main/java/solution zawiera gotowe rozwiązanie.

Instalowanie wymaganych pakietów i kompilowanie

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

Jeśli używasz Mavena 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 kodować, ale skonfigurujemy pliki zawierające odpowiednie tokeny uwierzytelniające dla interfejsów AdWords API i Content API dla Zakupów Google.

Konfigurowanie uwierzytelniania w interfejsie AdWords API

To ćwiczenie korzysta z tego samego sposobu wczytywania danych uwierzytelniających co biblioteka klienta, więc jeśli korzystasz już z biblioteki klienta interfejsów Google Ads API dla języka Java na swoim koncie menedżera, prawdopodobnie masz już wszystko skonfigurowane. W przeciwnym razie wykonaj czynności 1–3, aby rozpocząć korzystanie z biblioteki klienta interfejsów Google Ads API dla języka Java.

Konfigurowanie uwierzytelniania w Content API

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

1. Otwórz Merchant Center dla multikonta klientów i w menu wybierz Content API:
2. Kliknij kolejno Uwierzytelnianie i niebieski przycisk +:
3. Po zaakceptowaniu Warunków korzystania z usług Google Cloud Platform i interfejsów API Google Twój przeglądarka automatycznie pobierze plik JSON zawierający klucz nowego konta usługi.

Teraz postępuj zgodnie z instrukcjami konfigurowania uwierzytelniania w przypadku przykładowych kampanii Zakupy z kontem usługi. Oznacza to, że kopia klucza konta usługi powinna znajdować się pod ścieżką z Twojego katalogu domowego: shopping-samples/content/service-account.json. Nie musisz konfigurować konfiguracji próbek, chyba że chcesz wypróbować próbki po zakończeniu tego ćwiczenia.

Sprawdź

Teraz, gdy tokeny uwierzytelniania znajdują się we właściwych miejscach, spróbuj uruchomić przykłady. Jeśli używasz Mavena w wierszu poleceń, uruchom te polecenia:

mvn compile

Uwaga: jeśli zmienisz dowolny plik w folderze src/main/resources, nawet jeśli nie wprowadzisz żadnych zmian w kodzie (jak w tym kroku), przed uruchomieniem próbek ponownie skompiluj pliki, aby skopiować zmienione zasoby do folderu docelowego.

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

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

Ważne: framework, który udostępniliśmy, zakłada, że Twoje konto usługi Content API jest tylko użytkownikiem na Twoim koncie multiklienta. Jeśli pojawi się komunikat o błędzie z informacją, że Twoje konto usługi ma dostęp do więcej niż 1 konta, wykonaj czynności opisane powyżej, aby uzyskać klucz konta usługi przeznaczony do Twojego konta multikonta klientów.

4. Łączenie z interfejsami API

Teraz, gdy masz prawidłowe tokeny uwierzytelniania dla 2 interfejsów API, których będziemy używać, zacznijmy od uzupełnienia kodu. Zaczniemy od utworzenia obiektów sesji za pomocą tokenów uwierzytelniania. W kolejnych krokach użyjemy tych obiektów sesji, aby uzyskać dostęp do różnych usług i metod interfejsu API.

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 stworzenia pierwszego z nich, jest już dostępne w szkielecie kodu, więc wystarczy je 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ż obecne w szkielecie kodu. Sprawdź, gdzie należy je dodać.

Pomijamy też wszystkie instrukcje importowania klas interfejsów AdWords API i Content API, których używamy w tych fragmentach kodu. Jeśli nie używasz IDE, które może automatycznie dodawać poprawne importy, sprawdź kod w pakiecie solution pod kątem potrzebnych importów.

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

Tworzenie obiektu sesji w interfejsie 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 kreatorze użyjemy metody fromFile(), aby załadować je z pliku ads.properties skonfigurowanego w poprzednim kroku.

SolutionRunner.java

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

Sprawdź

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

mvn compile

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

Tym razem nie powinno wystąpić żadnych błędów, ale też nie uzyskasz żadnych interesujących wyników. Dodamy to, gdy wywołamy interfejsy API, aby utworzyć i połączyć nowe konta.

5. Tworzenie nowego zarządzanego konta AdWords

Po utworzeniu obiektów sesji interfejsu API utworzymy konta, które chcemy połączyć. Zaczniemy od AdWords i utworzymy konto testowe na 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 wyświetlimy tylko komentarz (// TODO...)), który wskazuje, gdzie należy umieścić te elementy w pierwszym komentarzu. Jeśli więc w tym i kolejnych krokach widzisz fragmenty kodu bez komentarza wprowadzającego, oznacza to, że są one bezpośrednio po poprzednim fragmencie.

Dostęp do ManagedCustomerService

W interfejsie AdWords API uzyskujemy dostęp do różnych dostępnych usług, pobierając najpierw wystąpienie klasy AdWordsServices za pomocą statycznej metody getInstance(). Za pomocą tego wystąpienia możemy 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);

Tutaj uzyskujemy dostęp do usługi ManagedCustomerService, która umożliwia zarządzanie „klientami” AdWords (kontami) z danego konta menedżera.

Określanie ustawień nowego konta

Najpierw utworzymy obiekt ManagedCustomer, który zawiera ustawienia nowego konta. Utworzymy konto testowe dla tego Codelab, ustawiając walutę na USD i strefę czasową na tę samą co na zachodnim wybrzeżu Stanów Zjednoczonych.

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ż losową liczbę, którą uwzględniamy w nazwie konta. Chcemy w ten sposób dopasować konto AdWords, które utworzymy tutaj, do konta Merchant Center, które utworzymy później. Dzięki temu będziemy mogli wizualnie sprawdzić te konta po zakończeniu tworzenia rozwiązania i sprawdzić, czy zostały one połączone.

Tworzenie nowego konta zarządzanego

Aby utworzyć nowe konto, użyjemy operacji 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 tutaj chcemy wykonać tylko jedną operację. Wynik metody mutate() to wartość zawierająca listę elementów ManagedCustomer. W tym przypadku będzie to lista zawierająca jednego klienta, czyli utworzone przez nas nowe konto. Pobranie identyfikatora tego nowego konta na przyszłość, a także wydrukowanie go, abyśmy mogli zobaczyć go jako część 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);

Sprawdź

Tak 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, nie powinno być żadnych błędów, a tym razem zobaczysz identyfikator utworzonego przez nas nowego konta AdWords. Sprawdź na stronie AdWords konto menedżera. Powinno się tam też wyświetlać nowe konto.

Uwaga: teraz każde uruchomienie rozwiązania będzie generować nowe konta. Po zakończeniu korzystania z rozwiązania możesz anulować utworzone konta AdWords na stronie AdWords. W końcu nasz schemat nazewnictwa tych kont ułatwia rozpoznanie, które z nich zostały utworzone przez nasz kod.

6. Tworzenie nowego subkonta Merchant Center

Na tym etapie utworzymy podkonto Merchant Center, które połączymy z kontem AdWords utworzonym w poprzednim kroku. Zamiast prosić o połączenie po utworzeniu subkonta, możemy poprosić o to podczas tworzenia, ponieważ mamy już identyfikator odpowiadającego mu konta AdWords.

Określ ustawienia nowego subkonta

W przeciwieństwie do interfejsu AdWords API metody setters klasy modelu Account zwracają obiekt, więc możemy je łączyć w łańcuchu wywołań w nowym obiekcie Account. Użyjemy też losowego numeru wygenerowanego podczas tworzenia konta AdWords w nazwie nowego konta 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")));

Jak już wspomnieliśmy we wstępie do tego kroku, ponieważ mamy już identyfikator AdWords nowego konta zarządzanego, możemy teraz dodać go do listy AdwordsLinks nowego subkonta. Gdy utworzysz nowe subkonto, zostanie automatycznie przesłane żądanie tego połączenia, które 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 potem wywołujemy metodę insert() bezpośrednio zamiast konfigurować obiekt operacji. Ta metoda przyjmuje 2 argumenty: identyfikator konta wieloklienta, 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 oryginalny obiekt Account, ponieważ zwrócona wersja zawiera ważną informację: identyfikator nowego subkonta. Wyświetlamy to w wyniku działania naszego rozwiązania, aby móc je uruchomić, a potem zweryfikować, czy nowe subkonto istnieje w Merchant Center.

Sprawdź

Jak poprzednio, uruchom 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, nie powinno być żadnych błędów. Tym razem zobaczysz identyfikatory zarówno nowego konta AdWords, jak i nowego konta Merchant Center. Aby zobaczyć nowe subkonto, otwórz Merchant Center na multikoncie klientów.

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

7. Zaakceptuj połączenie z konta AdWords

W ostatnim kroku utworzyliśmy nowe podkonto Merchant Center, prosząc jednocześnie o połączenie z naszym nowym kontem AdWords. Na tym etapie kończymy proces, akceptując żądane połączenie za pomocą interfejsu AdWords API.

Otwórz CustomerService.

Podobnie jak wcześniej, użyjemy klasy AdWordsServices, aby uzyskać klienta dla CustomerService. Jednak zanim utworzymy klienta, najpierw zmieniamy obiekt sesji AdWords, aby przyszłe użycia działały na nowym zarządzanym koncie zamiast na koncie menedżera. W końcu konto Merchant Center poprosiło 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śl prośbę o połączenie

Podobnie jak w przypadku tworzenia nowego konta AdWords, utworzymy obiekt ServiceLink zawierający ustawienia połączenia, a potem obiekt ServiceLinkOperation opisujący żądaną operację. Tutaj chcemy zastosować oczekujący link usługi do konta MERCHANT_CENTER i SET do konta ACTIVE. W przypadku ustawienia serviceLinkId użyjemy identyfikatora właśnie utworzonego konta Merchant Center, ponieważ jest on używany jako identyfikator linku usługi w 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);

Akceptowanie połączenia

Na koniec wywołamy metodę mutateServiceLinks() obiektu CustomerService, aby wykonać operację. Podobnie jak poprzednio, przyjmuje tablicę operacji łączenia usług. Tym razem metoda zwraca bezpośrednio listę (być może zmienionych) linków do usług, więc po prostu wydrukujemy wynik naszego rozwiązania, wykonując pętlę na tej liście. Ponieważ określiliśmy tylko jedną operację, w wyniku powinien zostać wydrukowany 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());
}

Sprawdź

Tak 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, nie powinno już być żadnych błędów. Tym razem zobaczysz też informację, że link do usługi został zaktualizowany i jest aktywny. Sprawdź AdWords i Merchant Center, aby upewnić się, że konta są połączone.

8. Warianty motywu

Gratulacje! Udało Ci się ukończyć ćwiczenia z programowania. Teraz, gdy masz w pełni działające rozwiązanie, sprawdźmy kilka przykładów modyfikacji lub rozszerzeń, które pozwolą Ci korzystać z większej liczby interfejsów API, których używaliśmy w tym laboratorium programistycznym.

Dodatkowe punkty: zaktualizuj istniejące konto Merchant Center, aby poprosić o połączenie z AdWords

W tym przypadku najpierw utworzyliśmy konto AdWords, aby móc użyć jego informacji do przesł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, aby najpierw utworzyć konto Merchant Center, a potem, gdy utworzysz konto AdWords, wróć do konfiguracji i poproś o połączenie.

Uwaga: musisz użyć metody Accounts.update lub Accounts.patch. Aby zrozumieć różnicę, spróbuj użyć obu wersji.

Ważne: nowe konto Merchant Center może nie być dostępne bezpośrednio po połączeniu z Accounts.insert. Dopóki nowe konto nie będzie dostępne, podczas próby uzyskania do niego dostępu lub jego modyfikacji pojawi się błąd HTTP 401. Przykłady w pliku Shopping zawierają przykład użycia strategii wzrastającego czasu do ponowienia w metodach AccountWorkflow.java, która używa metody retryFailures z pliku BaseWorkflowSample.java.

Dodatkowe punkty: aby potwierdzić utworzenie połączenia, pobierz informacje o kontach AdWords i Merchant Center

Obecnie aplikacja traktuje jako sukces tylko brak błędów w wywołaniach interfejsu API. Spróbuj rozszerzyć przykład, aby sprawdzić informacje o połączeniu nowych kont Merchant Center i AdWords i sprawdzić, czy połączenie jest rzeczywiście aktywne.

Uwaga: jeśli chodzi o Content API, warto przyjrzeć się metodzie Accounts.get. Po stronie AdWords użyj metody getServiceLinks obiektu CustomerServiceInterface.

Świat stoi przed Tobą otworem

Jeśli wpadnie Ci do głowy inna zmiana, spróbuj ją wprowadzić. Jeśli potrzebujesz kodu referencyjnego do swoich pomysłów, zapoznaj się z próbkami kodu Google Zakupy i katalogiem examples w źródle biblioteki klienta Google Ads w języku Java.