Tworzenie i łączenie subkont AdWords i Merchant Center

1. Wprowadzenie

W ramach tego ćwiczenia w Codelabs poznasz podstawy korzystania z interfejsów Content API for Shopping i AdWords API oraz utworzysz 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 kontem 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 (zalecamy IDE, które rozumie projekty Maven, takie jak Eclipse lub IntelliJ),

2. Przygotowanie

Pobierz

Kliknij poniższy link, aby pobrać cały kod do tego ćwiczenia w Codelabs:

Pobieranie kodu źródłowego

Rozpakuj pobrany plik ZIP. Spowoduje to rozpakowanie folderu głównego (shopping-account-linking-master), który zawiera projekt Maven oraz wszystkie potrzebne zasoby. Szczególnie ważne są następujące podkatalogi:

• src/main/java to źródłowy katalog główny projektu Maven i zawiera szkielet kodu, z którym możesz pracować.
• Pole src/main/java/solution zawiera gotowe rozwiązanie.

Zainstaluj wymagane pakiety i kompiluj

Jeśli używasz IDE 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 narzędzia 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

Na tym etapie nie będziemy kodować, tylko skonfigurować pliki zawierające odpowiednie tokeny uwierzytelniania dla interfejsów API AdWords i Content API for Shopping.

Konfigurowanie uwierzytelniania interfejsu API AdWords

W ramach tego ćwiczenia w Codelabs używamy tych samych danych logowania co biblioteka kliencka, więc jeśli masz już za sobą korzystanie na koncie menedżera z biblioteki klienta interfejsów API Google Ads dla języka Java, wszystko powinno być już skonfigurowane. W przeciwnym razie wykonaj kroki 1–3, aby zacząć korzystać z biblioteki klienta interfejsów API Google Ads dla języka Java.

Konfigurowanie uwierzytelniania Content API

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

1. Otwórz Merchant Center dla swojego multikonta klientów i z rozszerzonego menu wybierz Content API:
2. Wybierz Authentication (Uwierzytelnianie) i kliknij niebieski przycisk +:
3. Po zaakceptowaniu Warunków korzystania z usługi Google Cloud Platform i interfejsów API Google przeglądarka automatycznie pobierze plik JSON zawierający nowy klucz konta usługi.

Teraz postępuj zgodnie z instrukcjami konfigurowania uwierzytelniania dla próbek w Zakupach Google za pomocą konta usługi. Oznacza to, że kopia klucza konta usługi powinna się znajdować w tej ścieżce z katalogu głównego: shopping-samples/content/service-account.json. Nie musisz konfigurować przykładowych konfiguracji, chyba że chcesz wypróbować je po ukończeniu tego ćwiczenia w Codelabs.

Wypróbuj

Teraz gdy masz już tokeny uwierzytelniania w odpowiednich miejscach, spróbuj uruchomić próbki. Jeśli używasz narzędzia Maven w wierszu poleceń, uruchom te polecenia:

mvn compile

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

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

Jeśli pojawi się komunikat o błędzie informujący, że obiekty sesji nie są podane, oznacza to, że tokeny uwierzytelniania zostały umieszczone i działają prawidłowo. W przeciwnym razie komunikat o błędzie powinien zawierać informację o tym, które dane logowania nie zadziałały i który plik należy poprawić.

Ważne: opracowana przez nas platforma zakłada, że Twoje konto usługi Content API jest wymienione tylko jako użytkownik na 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 multikonta klientów.

4. Połącz się z interfejsami API

Skoro masz już prawidłowe tokeny uwierzytelniania dla 2 interfejsów API, których będziemy używać, możemy zacząć wpisywać faktyczny kod. Zaczniemy od tworzenia obiektów sesji przy użyciu naszych tokenów uwierzytelniania. W późniejszych krokach dowiemy się, jak za pomocą tych obiektów sesji udostępnia różne usługi i metody dostarczane przez poszczególne interfejsy 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 do stworzenia pierwszego kodu jest już szkielet kodu, więc wystarczy go 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 już istnieją w szkieletie kodu. Poszukaj ich, aby zobaczyć, gdzie należy dodać te wiersze.

Pomijamy też wszystkie niezbędne instrukcje importu dla klas interfejsu 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ć prawidłowe importy, sprawdź kod w pakiecie solution pod kątem wymaganych importów.

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

Tworzenie obiektu sesji interfejsu AdWords API

Istnieje też klasa AdWordsSession.Builder do tworzenia obiektów AdWordsSession. Główna różnica polega na tym, że zamiast ustawiać opcje konfiguracji bezpośrednio w kreatorze, do wczytywania ich z pliku ads.properties skonfigurowanego w poprzednim kroku użyjemy metody fromFile().

SolutionRunner.java

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

Wypróbuj

Jeśli korzystasz z 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 powinny pojawić się żadne błędy, ale nie pojawią się też żadne interesujące wyniki. Dodamy go podczas wywoływania interfejsów API w celu utworzenia i połączenia nowych kont.

5. Tworzenie nowego zarządzanego konta AdWords

Po utworzeniu obiektów sesji interfejsu API przejdziemy do utworzenia kont, które chcemy połączyć. Zaczniemy od AdWords i utworzymy konto testowe pod naszym kontem menedżera.

Uwaga: wszystkie fragmenty kodu z tej sekcji są dodawane w tym samym miejscu w szkieletie w przedstawionej kolejności. Dlatego pokazujemy tylko komentarz (// TODO...), który wskazuje, gdzie go umieścić w pierwszym. Tak więc w tej i kolejnych krokach fragmenty kodu bez komentarza wprowadzającego pojawiają się bezpośrednio po poprzednim fragmencie.

Uzyskiwanie dostępu do usługi ManagedCustomerService

W interfejsie API AdWords uzyskujemy dostęp do różnych dostępnych usług, pobierając wystąpienie klasy AdWordsServices za pomocą statycznej metody getInstance(). Za pomocą tej instancji możemy następnie utworzyć klienty dla tych usług za pomocą metody get(), która wymaga 2 argumentów: sesji, dla której zostanie utworzony klient, i interfejsu żą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);

Uzyskujemy tu dostęp do usługi ManagedCustomerService, która pozwala zarządzać „klientami” AdWords (konta) z danego konta menedżera.

Określanie nowych ustawień konta

Najpierw utworzymy obiekt ManagedCustomer zawierający ustawienia nowego konta. Utworzymy konto testowe na potrzeby tego ćwiczenia w Codelabs. Ustawimy jego walutę na USD, a strefę czasową na zachodnie wybrzeże 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ż losowy numer, który umieszczamy w nazwie konta. Trzeba tylko połączyć utworzone tu konto AdWords z kontem Merchant Center, które utworzymy później, aby móc przyjrzeć się im wzrokowo po zakończeniu naszego rozwiązania i upewnić się, że oba konta rzeczywiście są 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ę, używając metody mutate() obiektu ManagedCustomerService. Ta metoda wymaga wykonania szeregu operacji, a tutaj chcemy wykonać tylko jedną operację. Wynikiem metody mutate() jest wartość zawierająca listę elementów ManagedCustomer; będzie to lista z jednym klientem – nowe konto, które utworzyliśmy. Pozyskamy identyfikator tego nowego konta do użycia w przyszłości, a także wydrukujemy go, aby był widoczny w wyniku 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);

Wypróbuj

Tak jak poprzednio uruchom rozwiązanie. Jeśli używasz narzędzia Maven z poziomu wiersza poleceń:

mvn compile

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

Jeśli wszystko przebiegnie prawidłowo, nie powinny się już pojawić żadne błędy, a tym razem pojawi się identyfikator nowo utworzonego konta AdWords. Wejdź na stronę AdWords swojego konta menedżera – nowe konto również powinno być tam widoczne.

Uwaga: od tego momentu każde uruchomienie rozwiązania będzie powodować generowanie nowych kont. Po zastosowaniu rozwiązania możesz zlikwidować każde utworzone konto AdWords na stronie AdWords. Ostatecznie nasz schemat nazewnictwa tych kont ułatwia określenie, 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 AdWords utworzonym w ostatnim kroku. Zamiast osobno prosić o połączenie po utworzeniu subkonta, możemy o nie poprosić podczas jego tworzenia, ponieważ znamy już identyfikator odpowiedniego konta AdWords.

Określanie ustawień nowego subkonta

W przeciwieństwie do interfejsu AdWords API elementy ustalające klasy modelu Account zwracają obiekt, więc można połączyć nasze wywołania z nowym obiektem Account. W nazwie nowego konta Merchant Center użyjemy również losowej liczby wygenerowanej podczas tworzenia konta AdWords.

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 na wstępie do tego kroku, mamy już identyfikator AdWords nowego zarządzanego konta, więc możemy dodać go do listy AdwordsLinks na nowym subkoncie. Po utworzeniu nowego subkonta zostanie automatycznie wysłane żądanie połączenia z tym kontem i będzie ono dostępne w interfejsie API AdWords.

Utwórz nowe subkonto

W interfejsie Content API wywołujemy metodę accounts() obiektu sesji, aby uzyskać dostęp do usługi Accounts, a następnie bezpośrednio wywołuje metodę insert(), zamiast konfigurować obiekt operacji. Ta metoda przyjmuje 2 argumenty: identyfikator multikonta klientów, w ramach którego ma zostać utworzone nowe subkonto, i obiekt Account zawierający odpowiednie 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 pierwotny obiekt Account, ponieważ zwrócona wersja zawiera ważną informację: identyfikator nowego subkonta. Drukujemy je w danych wyjściowych rozwiązania, dzięki czemu możemy je uruchomić, a następnie sprawdzić, czy w Merchant Center istnieje nowe subkonto.

Wypróbuj

Tak jak poprzednio uruchom rozwiązanie. Jeśli używasz narzędzia Maven z poziomu wiersza poleceń:

mvn compile

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

Jeśli wszystko przebiegnie prawidłowo, wciąż nie będzie żadnych błędów, a tym razem będziemy widzieć identyfikatory zarówno nowego konta AdWords, jak i nowego konta Merchant Center. Sprawdź Merchant Center na swoim multikoncie klientów, aby zobaczyć na nim nowe subkonto.

Uwaga: podobnie jak w przypadku AdWords, każde uruchomienie tego rozwiązania spowoduje generowanie nowych kont Merchant Center. Gdy skończysz korzystać z rozwiązania, możesz usunąć wszystkie utworzone subkonta w Merchant Center.

7. Zaakceptuj połączenie z konta AdWords

W ostatnim kroku utworzyliśmy nowe subkonto Merchant Center i jednocześnie poprosiliśmy o połączenie z nowym kontem AdWords. W tym kroku zakończymy proces, używając interfejsu API AdWords do zaakceptowania żądanego połączenia.

Uzyskaj dostęp do CustomerService.

Tak jak wcześniej, użyjemy klasy AdWordsServices, aby uzyskać klienta dla CustomerService. Jednak przed utworzeniem klienta musimy zmienić obiekt sesji AdWords w taki sposób, aby przyszłe zastosowania były wykonywane na nowym zarządzanym koncie, a nie na koncie menedżera. Ostatecznie konto Merchant Center poprosiło o połączenie z zarządzanym kontem, 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);

Podaj żądany link

Podobnie jak podczas tworzenia nowego konta AdWords, utworzymy obiekt ServiceLink zawierający ustawienia połączenia, a następnie obiekt ServiceLinkOperation, który opisuje żądaną operację. W tym przypadku chcemy przenieść oczekujące połączenie usługi z kontem MERCHANT_CENTER i SET je użytkownikowi ACTIVE. W przypadku ustawienia serviceLinkId użyjemy identyfikatora właśnie utworzonego konta Merchant Center, ponieważ służy on jako identyfikator połączenia 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);

Zaakceptuj link

Na koniec wywołamy metodę mutateServiceLinks() obiektu CustomerService, by wykonać tę operację. Tak jak wcześniej, potrzebna jest tablica operacji połączenia usług. Tym razem metoda zwraca bezpośrednio listę (prawdopodobnie zmienionych) linków usługi, więc wyświetlimy wynik rozwiązania, zapętlając tę listę. Oczywiście określiliśmy tylko jedną operację, więc w danych wyjściowych powinien pojawić się 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());
}

Wypróbuj

Tak jak poprzednio uruchom rozwiązanie. Jeśli używasz narzędzia 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 pojawi się komunikat, że link do usługi został zaktualizowany i jest aktywny. Otwórz AdWords i Merchant Center i sprawdź, czy konta są teraz połączone.

8. Odmiany na temat motywu

Gratulujemy ukończenia ćwiczenia z programowania. Skoro masz już w pełni działające rozwiązanie, zobaczmy, jak można je zmodyfikować lub rozszerzyć, aby można było korzystać z większej liczby interfejsów API przedstawionych w tym ćwiczeniu z programowania.

Dodatkowa kwota: zaktualizuj istniejące konto Merchant Center, aby poprosić o połączenie z Google Ads

W ramach ćwiczenia w Codelabs utworzyliśmy konto AdWords, aby użyć jego danych 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 następnie wróć po utworzeniu konta AdWords i zaktualizuj jego konfigurację, aby poprosić o połączenie.

Uwaga: wybierz metodę Accounts.update lub Accounts.patch. Wypróbuj po kolei poszczególne wersje, aby zrozumieć różnicę.

Ważne: nowe konto Merchant Center może nie być dostępne natychmiast po wywołaniu usługi Accounts.insert. Dopóki nowe konto nie będzie dostępne, podczas próby uzyskania dostępu do niego lub jego modyfikacji będzie się pojawiał błąd HTTP 401. W przykładach dotyczących Zakupów Google przedstawiono przykład wykorzystania wykładniczego czasu do ponowienia w celu ponawiania metod w AccountWorkflow.java, który wykorzystuje metodę retryFailures z BaseWorkflowSample.java.

Dodatkowa kwota: sprawdź, czy udało się utworzyć połączenie, pobierając informacje o kontach AdWords i Merchant Center

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

Uwaga: od strony interfejsu Content API warto spojrzeć na metodę Accounts.get. Po stronie AdWords użyj metody getServiceLinks obiektu CustomerServiceInterface.

Z całego świata nie możesz się doczekać

Jeśli myślisz o innych zmianach, które możesz wprowadzić, wypróbuj je. Jeśli potrzebujesz kodu referencyjnego, przejrzyj przykłady korzystania z Zakupów Google i katalog examples w źródle biblioteki klienta Google Ads w języku Java.