Creazione e collegamento di subaccount AdWords e Merchant Center

1. Introduzione

In questo codelab, apprenderai alcune nozioni di base sull'utilizzo dell'API Content for Shopping e dell'API AdWords e imparerai a creare un'applicazione che utilizza entrambe. In particolare, creerai un'applicazione a riga di comando che creerà e collegherà un account AdWords e un account Merchant Center.

Cosa imparerai a fare

• Come creare account AdWords gestiti da un account amministratore.
• Come creare account Merchant Center gestiti da un account multi-cliente.
• Come richiedere un collegamento da un account Merchant Center a un account AdWords.
• Come accettare un collegamento a Merchant Center in attesa in un account AdWords.

Che cosa ti serve

• Un account amministratore AdWords.
• Un account multi-cliente Merchant Center.
• Java 7 e versioni successive
• Maven
• Il codice campione
• Un editor di testo (è consigliato un IDE che comprenda i progetti Maven come Eclipse o IntelliJ)

2. Preparazione

Scarica il codo

Fai clic sul seguente link per scaricare tutto il codice per questo codelab:

Scarica il codice sorgente

Apri il file ZIP scaricato. Verrà aperta una cartella principale (shopping-account-linking-master), che contiene un progetto Maven insieme a tutte le risorse di cui hai bisogno. Di particolare interesse sono le seguenti sottodirectory:

• src/main/java è la radice di origine del progetto Maven e contiene uno scheletro di codice in cui lavorare.
• src/main/java/solution contiene la soluzione completa.

Installa i pacchetti richiesti e crea

Se utilizzi un IDE Maven sensibile come Eclipse o IntelliJ, puoi importare la cartella estratta come progetto Maven e poi compilare il progetto normalmente.

Se utilizzi Maven dalla riga di comando, puoi eseguire il comando seguente per recuperare i pacchetti necessari e compilare il progetto dalla cartella principale del progetto decompresso (shopping-account-linking-master):

mvn compile

3. Configura l'autenticazione

Per questo passaggio, non eseguiremo alcuna codifica, ma imposteremo file contenenti i token di autenticazione appropriati per l'API AdWords e l'API Content for Shopping.

Configura l'autenticazione dell'API di AdWords

Questo codelab utilizza le stesse credenziali di caricamento della libreria client. Di conseguenza, se hai già utilizzato la libreria client delle API di Google Ads per Java con il tuo account amministratore, dovresti essere già configurato. In caso contrario, segui i passaggi da 1 a 3 per iniziare a utilizzare la libreria client delle API di Google Ads per Java.

Configura l'autenticazione Content API

Se non hai ancora una chiave dell'account di servizio:

1. Accedi a Merchant Center per il tuo account multi-cliente e seleziona Content API dal menu extra:
2. Seleziona Autenticazione, quindi fai clic sul pulsante + blu:
3. Dopo aver accettato i Termini di servizio della piattaforma Google Cloud e delle API di Google, il browser scaricherà automaticamente un file JSON contenente la nuova chiave dell'account di servizio.

Ora segui le istruzioni per la configurazione dell'autenticazione per gli esempi di Shopping con un account di servizio. Ciò significa che una copia della chiave dell'account di servizio dovrebbe trovarsi nel seguente percorso della home directory: shopping-samples/content/service-account.json. Non è necessario impostare la configurazione degli esempi, a meno che tu non voglia provarli dopo aver completato questo codelab.

Mettiti alla prova

Ora che i token di autenticazione si trovano nelle posizioni corrette, prova a eseguire gli esempi. Se utilizzi Maven alla riga di comando, esegui questi comandi:

mvn compile

Nota: se modifichi uno qualsiasi dei file in src/main/resources, anche se non apporti modifiche al codice (come in questo passaggio), lo ricompila prima di eseguire gli esempi per copiare le risorse modificate nella destinazione.

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

Se ricevi un messaggio di errore che indica che gli oggetti sessione non sono stati forniti, significa che i token di autenticazione sono attivi e funzionano correttamente. In caso contrario, il messaggio di errore visualizzato dovrebbe indicare le credenziali che non hanno funzionato e il file da correggere.

Importante: il framework che abbiamo fornito presuppone che il tuo account di servizio API Content sia elencato solo come utente nel tuo account multi-cliente. Se ricevi un messaggio di errore che indica che il tuo account di servizio ha accesso a più di un account, segui i passaggi precedenti per ottenere una chiave dell'account di servizio specifica per il tuo account multi-cliente.

4. Connettiti alle API

Ora che disponi di token di autenticazione validi per le due API che utilizzeremo, iniziamo a compilare il codice vero e proprio. Inizieremo con la creazione di oggetti sessione utilizzando i nostri token di autenticazione. Nei passaggi successivi, accederemo ai vari servizi e metodi forniti da ciascuna API utilizzando questi oggetti di sessione.

Creare un oggetto sessione API Content

Per creare una sessione API Content, creeremo un oggetto ShoppingContent.Builder e lo utilizzeremo per creare l'oggetto ShoppingContent appropriato. Fortunatamente, tutto ciò di cui abbiamo bisogno per creare il primo è già disponibile nello scheletro di codice, quindi dobbiamo solo combinarlo in questo modo:

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

Nota: i commenti iniziali in questo esempio di codice e in quelli successivi esistono già nello scheletro di codice. Cercali per vedere dove aggiungere queste righe.

Inoltre, omettiamo qualsiasi dichiarazione di importazione necessaria per le classi API Content e API di AdWords utilizzate in questi snippet. Se non utilizzi un IDE che può aggiungere automaticamente le importazioni corrette, verifica il codice nel pacchetto solution per verificare le importazioni necessarie.

L'impostazione di un nome di applicazione non è strettamente necessaria, ma mostra come impostare le opzioni desiderate tramite l'oggetto ShoppingContent.Builder prima di chiamare il metodo build().

Creare un oggetto di sessione dell'API AdWords

Analogamente, esiste una classe AdWordsSession.Builder per creare oggetti AdWordsSession. La differenza principale è che, invece di impostare le opzioni di configurazione direttamente nello strumento di creazione, useremo il metodo fromFile() per caricarle dal file ads.properties che abbiamo configurato nel passaggio precedente.

SolutionRunner.java

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

Mettiti alla prova

Utilizzeremo gli stessi comandi dell'ultima sezione per ricreare ed eseguire il progetto Maven, se lo esegui dalla riga di comando:

mvn compile

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

Questa volta non dovresti visualizzare alcun errore, anche se non otterrai output interessanti. Lo aggiungeremo quando chiameremo le API per creare e collegare i nuovi account.

5. Crea un nuovo account AdWords gestito

Dopo aver creato gli oggetti di sessione API, passiamo alla creazione degli account da collegare. Inizieremo con AdWords e creeremo un account di prova all'interno del nostro account amministratore.

Nota:tutti gli snippet di codice in questa sezione vengono aggiunti alla stessa posizione nel codice dello scheletro nell'ordine presentato. Per questo motivo, mostreremo solo il commento (// TODO...) che indica dove inserirlo nel primo. Di conseguenza, in questo passaggio e in quelli futuri, gli snippet di codice che non contengono un commento introduttivo verranno inseriti subito dopo lo snippet precedente.

Accedi a ManagedCustomerService

Nell'API di AdWords, accediamo ai vari servizi disponibili recuperando innanzitutto un'istanza della classe AdWordsServices utilizzando il metodo getInstance() statico. Utilizzando questa istanza, possiamo quindi creare client per questi servizi tramite il metodo get(), che accetta due argomenti: la sessione per la quale creare il client e l'interfaccia del servizio desiderato.

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

Qui accediamo a ManagedCustomerService, che ci consente di gestire i "clienti" di AdWords (account) di un determinato account amministratore.

Specificare le nuove impostazioni dell'account

Per prima cosa, creeremo un oggetto ManagedCustomer contenente le impostazioni del nuovo account. Creeremo un account di prova per questo codelab, impostando la valuta su USD e il fuso orario sullo stesso valore della costa occidentale degli Stati Uniti.

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

Creiamo anche un numero casuale che includiamo nel nome dell'account. Questo ci consente solo di abbinare l'account AdWords che creeremo qui all'account Merchant Center che creeremo più avanti. In questo modo potremo esaminarlo visivamente quando la nostra soluzione sarà completa e assicurarci che i due siano collegati.

Crea il nuovo account gestito

Per creare effettivamente il nuovo account, utilizzeremo ManagedCustomerOperation per specificare un'operazione ADD:

SolutionRunner.java

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

Successivamente, eseguiremo l'operazione utilizzando il metodo mutate() dell'oggetto ManagedCustomerService. Questo metodo richiede un array di operazioni, ma in questo caso vogliamo eseguire una sola operazione. Il risultato del metodo mutate() è un valore contenente un elenco di ManagedCustomer; sarà un elenco contenente un cliente, il nuovo account che abbiamo creato. Recupereremo l'ID del nuovo account per utilizzarlo in futuro e lo stamperemo in modo da poterlo visualizzare come parte dell'output della nostra soluzione.

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

Mettiti alla prova

Prova a eseguire la soluzione come prima. Se utilizzi Maven dalla riga di comando:

mvn compile

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

Se tutto funziona correttamente, dovresti comunque non visualizzare errori e questa volta esamineremo l'ID del nuovo account AdWords che abbiamo creato. Visita il sito AdWords per il tuo account amministratore, dove dovresti vedere anche il nuovo account.

Nota: a questo punto, ogni esecuzione della soluzione genererà nuovi account. Una volta eseguita la soluzione, puoi cancellare qualsiasi account AdWords creato tramite il sito AdWords. Dopotutto, il nostro schema di denominazione per questi account consente di capire facilmente quali sono stati creati dal nostro codice.

6. Crea un nuovo subaccount Merchant Center

In questo passaggio creeremo il subaccount Merchant Center che collegheremo all'account AdWords creato nell'ultimo passaggio. Anziché richiedere un collegamento separatamente dopo aver creato il subaccount, possiamo richiederlo in fase di creazione, dato che disponiamo già dell'ID dell'account AdWords corrispondente.

Specificare le impostazioni per il nuovo subaccount

A differenza dell'API AdWords, i setter per la classe del modello Account restituiscono l'oggetto, quindi possiamo concatenare le nostre chiamate sul nuovo oggetto Account. Il numero casuale generato durante la creazione dell'account AdWords verrà utilizzato anche nel nome del nuovo account 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")));

Come menzionato nell'introduzione di questo passaggio, poiché disponiamo già dell'ID AdWords per il nuovo account gestito, possiamo aggiungerlo ora all'elenco di AdwordsLinks per il nuovo subaccount. Quando il nuovo subaccount viene creato, questo collegamento verrà richiesto automaticamente e sarà disponibile nell'API di AdWords.

Crea il nuovo subaccount

Nell'API Content, chiamiamo il metodo accounts() dell'oggetto session per accedere al servizio Accounts, quindi chiamiamo direttamente il metodo insert() invece di configurare un oggetto operazione. Questo metodo accetta due argomenti: l'ID dell'account multi-cliente in base al quale creare il nuovo subaccount e l'oggetto Account che contiene le impostazioni desiderate:

SolutionRunner.java

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

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

Il metodo insert() restituisce un oggetto Account che contiene le impostazioni per il nuovo subaccount. L'oggetto Account originale viene sovrascritto perché la versione restituita include un'informazione importante: l'ID del nuovo subaccount. Lo stampiamo nell'output della nostra soluzione, in modo da poter eseguire la soluzione e poi verificare che il nuovo subaccount esista in Merchant Center.

Mettiti alla prova

Prova a eseguire la soluzione come prima. Se utilizzi Maven dalla riga di comando:

mvn compile

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

Se tutto funziona correttamente, dovresti comunque non visualizzare errori e questa volta vedremo gli ID sia del nuovo account AdWords sia del nuovo account Merchant Center. Accedi al tuo account multi-cliente in Merchant Center per visualizzare il nuovo subaccount.

Nota: come con AdWords, ogni versione della soluzione genererà nuovi account Merchant Center. Una volta completata l'esecuzione della soluzione, puoi eliminare i subaccount creati tramite Merchant Center.

7. Accettare il collegamento dall'account AdWords

Nell'ultimo passaggio, abbiamo creato un nuovo subaccount Merchant Center, richiedendo contemporaneamente il collegamento al nostro nuovo account AdWords. In questo passaggio, concluderemo la procedura utilizzando l'API AdWords per accettare il link richiesto.

Accedere all'CustomerService

Come prima, utilizzeremo la classe AdWordsServices per acquisire un cliente per CustomerService. Tuttavia, prima di creare il cliente, modifichiamo l'oggetto sessione AdWords in modo che gli utilizzi futuri vengano eseguiti sul nuovo account gestito anziché sull'account amministratore. Dopo tutto, l'account Merchant Center ha richiesto un collegamento all'account gestito, non all'account amministratore.

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

Specifica il link richiesto

Come per il nuovo account AdWords, viene creato un oggetto ServiceLink che contiene le impostazioni del collegamento e successivamente un oggetto ServiceLinkOperation che descrive l'operazione desiderata. In questo caso vogliamo trasferire il collegamento al servizio in attesa in un account MERCHANT_CENTER e SET in ACTIVE. Per l'impostazione serviceLinkId, useremo l'ID dell'account Merchant Center appena creato, utilizzato per l'ID del collegamento al servizio in 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);

Accettare il collegamento

Infine, chiameremo il metodo mutateServiceLinks() dell'oggetto CustomerService per eseguire l'operazione. Come in precedenza, sono necessarie una serie di operazioni di collegamento dei servizi. Questa volta, il metodo restituisce un elenco di link ai servizi (eventualmente modificati) direttamente, quindi il risultato della soluzione viene stampato eseguendo il loop su quell'elenco. Naturalmente, poiché abbiamo specificato una sola operazione, ti aspetti che venga stampato un solo link nell'output.

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

Mettiti alla prova

Prova a eseguire la soluzione come prima. Se utilizzi Maven dalla riga di comando:

mvn compile

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

Se tutto funziona correttamente, dovresti comunque non riscontrare errori e questa volta vedrai anche una nota che ti informa che il link al servizio è stato aggiornato in modo che sia attivo. Controlla AdWords e Merchant Center e verifica che gli account siano ora collegati.

8. Variazioni su un tema

Complimenti per aver completato il codelab. Ora che hai una soluzione completamente funzionante, diamo un'occhiata ad alcuni esempi di come potresti modificarla o estenderla per utilizzare più delle API che hai visto in questo codelab.

Credito aggiuntivo: aggiorna un account Merchant Center esistente per richiedere un collegamento ad AdWords

Nel codelab, abbiamo creato prima l'account AdWords in modo intelligente in modo da poter utilizzare le relative informazioni per richiedere il collegamento al momento della creazione dell'account Merchant Center. Tuttavia, se l'account Merchant Center esiste già, dovrai aggiornare la sua configurazione. Prova a modificare il codice per creare l'account Merchant Center, poi torna indietro dopo aver creato l'account AdWords e aggiorna la sua configurazione per richiedere il collegamento.

Nota: ti consigliamo di utilizzare il metodo Accounts.update o Accounts.patch. Anzi, prova una versione con ognuno per capire la differenza.

Importante: un nuovo account Merchant Center potrebbe non essere disponibile subito dopo la chiamata al numero Accounts.insert. Finché il nuovo account non sarà disponibile, riceverai un errore HTTP 401 quando tenti di accedervi o di modificarlo. Gli esempi di Shopping mostrano un esempio di utilizzo del backoff esponenziale per riprovare i metodi in AccountWorkflow.java, che utilizza il metodo retryFailures di BaseWorkflowSample.java.

Credito aggiuntivo: verifica la creazione del collegamento recuperando i dati degli account AdWords e Merchant Center

Attualmente, l'applicazione considera solo l'assenza di errori nelle chiamate API come un segno di successo. Prova a estendere l'esempio per verificare le informazioni sul collegamento dei nuovi account Merchant Center e AdWords e verificare che il collegamento sia effettivamente attivo.

Nota:sul lato dell'API Content, dovrai prendere in considerazione il metodo Accounts.get. In AdWords, ti consigliamo di utilizzare il metodo getServiceLinks dell'oggetto CustomerServiceInterface.

Il mondo è al tuo fianco

Se pensi ad altre modifiche che potresti apportare, provale! Se hai bisogno di un codice di riferimento per le tue idee, consulta gli esempi di Google Shopping e la directory examples nell'origine della libreria client Java di Google Ads.