Creazione e collegamento di subaccount AdWords e Merchant Center

1. Introduzione

In questo codelab imparerai alcune nozioni di base sull'utilizzo dell' API Content for Shopping e dell' API AdWords e creerai un'applicazione che le 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 Merchant Center in attesa in un account AdWords.

Che cosa ti serve

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

2. Preparazione

Scaricare il codice

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

Scarica il codice sorgente

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

• 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.

Installare i pacchetti richiesti e creare

Se utilizzi un IDE compatibile con Maven 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 seguente comando per recuperare i pacchetti necessari e compilare il progetto dalla cartella principale del progetto decompresso (shopping-account-linking-master):

mvn compile

3. Configurare l'autenticazione

In questo passaggio non scriveremo codice, ma configureremo i file che contengono i token di autenticazione appropriati per l'API AdWords e l'API Content for Shopping.

Configurare l'autenticazione dell'API AdWords

Questo codelab utilizza lo stesso caricamento delle credenziali della libreria client, quindi se hai già utilizzato la libreria client delle API Google Ads per Java con il tuo account amministratore, dovresti aver già completato la configurazione. In caso contrario, segui i passaggi da 1 a 3 per iniziare a utilizzare la libreria client delle API Google Ads per Java.

Configurare l'autenticazione dell'API Content

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

1. Vai a Merchant Center per il tuo account multi-cliente e seleziona API Content dal menu overflow:
2. Seleziona Autenticazione, quindi fai clic sul pulsante blu +:
3. Dopo aver accettato i Termini di servizio di Google Cloud Platform e delle API Google, il browser scaricherà automaticamente un file JSON contenente la chiave del nuovo service account.

Ora segui le istruzioni per configurare l'autenticazione per gli esempi di Shopping con un account di servizio. Ovvero, una copia della chiave dell'account di servizio deve trovarsi nel seguente percorso dalla directory home: shopping-samples/content/service-account.json. Non è necessario configurare gli esempi, a meno che tu non voglia provarli dopo aver completato questo codelab.

Provare

Ora che hai i token di autenticazione nelle posizioni corrette, prova a eseguire gli esempi. Se utilizzi Maven dalla riga di comando, esegui i seguenti comandi:

mvn compile

Nota: se modifichi uno dei file in src/main/resources, anche se non apporti modifiche al codice (come in questo passaggio), 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 della sessione non sono stati forniti, significa che i token di autenticazione sono attivi e funzionano correttamente. In caso contrario, il messaggio di errore dovrebbe indicare quali credenziali non hanno funzionato e quale file correggere.

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

4. Connettersi alle API

Ora che hai token di autenticazione validi per le due API che utilizzeremo, iniziamo a compilare il codice effettivo. Inizieremo creando oggetti sessione utilizzando i nostri token di autenticazione. Nei passaggi successivi, accederemo ai vari servizi e metodi forniti da ogni API utilizzando questi oggetti sessione.

Creare un oggetto sessione dell'API Content

Per creare una sessione dell'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 assemblarlo come segue:

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 e nei seguenti esempi di codice esistono già nello scheletro di codice. Cercali per vedere dove devono essere aggiunte queste righe.

Omettiamo anche le istruzioni di importazione necessarie per le classi dell'API AdWords e dell'API Content che utilizziamo in questi snippet. Se non utilizzi un IDE in grado di aggiungere automaticamente le importazioni corrette, controlla il codice nel pacchetto solution per le importazioni necessarie.

L'impostazione di un nome dell'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 sessione dell'API AdWords

Analogamente, esiste una classe AdWordsSession.Builder per creare oggetti AdWordsSession. La differenza principale è che, anziché impostare le opzioni di configurazione direttamente sul builder, utilizzeremo 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();

Provare

Se esegui il progetto Maven dalla riga di comando, utilizzeremo gli stessi comandi della sezione precedente per ricompilarlo ed eseguirlo:

mvn compile

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

Questa volta non dovresti ricevere alcun errore, ma non otterrai nemmeno un output interessante. Lo aggiungeremo quando chiameremo le API per creare e collegare i nuovi account.

5. Creare un nuovo account AdWords gestito

Ora che abbiamo creato gli oggetti sessione dell'API, creeremo gli account che vogliamo collegare. Inizieremo con AdWords e creeremo un account di test nel nostro account amministratore.

Nota: tutti gli snippet di codice in questa sezione vengono aggiunti nello stesso punto del codice scheletro nell'ordine in cui vengono presentati. Per questo motivo, mostreremo solo il commento (// TODO...) che indica dove inserirli nel primo. Pertanto, in questo e nei passaggi successivi, se vedi snippet di codice senza un commento introduttivo, questi vanno inseriti immediatamente dopo lo snippet precedente.

Accedere a ManagedCustomerService

Nell'API AdWords, accediamo ai vari servizi disponibili recuperando prima un'istanza della classe AdWordsServices utilizzando il metodo statico getInstance(). Utilizzando questa istanza, possiamo quindi creare client per questi servizi tramite il metodo get(), che accetta due argomenti: la sessione per cui creare il client e l'interfaccia per il 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" (account) AdWords da un determinato account amministratore.

Specificare le impostazioni del nuovo account

Innanzitutto, creeremo un oggetto ManagedCustomer che contiene le impostazioni del nuovo account. Per questo codelab creeremo un account di test, impostando la valuta su USD e il fuso orario sullo stesso 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 di abbinare l'account AdWords che creeremo qui all'account Merchant Center che creeremo in un secondo momento, in modo da poterli esaminare visivamente una volta completata la soluzione e assicurarci che i due siano effettivamente collegati.

Creare il nuovo account gestito

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

SolutionRunner.java

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

Eseguiremo quindi l'operazione utilizzando il metodo mutate() dell'oggetto ManagedCustomerService. Questo metodo accetta un array di operazioni da eseguire, ma qui vogliamo eseguire una sola operazione. Il risultato del metodo mutate() è un valore contenente un elenco di ManagedCustomer; in questo caso, sarà un elenco contenente un cliente, il nuovo account che abbiamo creato. Recupereremo l'ID del nuovo account per un utilizzo futuro e lo stamperemo anche 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);

Provare

Come prima, prova a eseguire la soluzione. Se utilizzi Maven dalla riga di comando:

mvn compile

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

Se tutto va bene, non dovresti visualizzare errori e questa volta vedrai l'ID del nuovo account AdWords che abbiamo creato. Controlla il sito AdWords per il tuo account amministratore e dovresti vedere anche il nuovo account.

Nota: a questo punto, ogni esecuzione della soluzione genererà nuovi account. Puoi annullare gli account AdWords creati tramite il sito AdWords al termine dell'esecuzione della soluzione. Dopotutto, la nostra convenzione di denominazione per questi account consente di vedere facilmente quali sono stati creati dal nostro codice.

6. Creare un nuovo subaccount Merchant Center

In questo passaggio creeremo il subaccount Merchant Center che collegheremo all'account AdWords creato nel passaggio precedente. Anziché richiedere separatamente un collegamento dopo aver creato il subaccount, possiamo richiedere il collegamento durante la creazione, poiché abbiamo già l'ID dell'account AdWords corrispondente.

Specificare le impostazioni del nuovo subaccount

A differenza dell'API AdWords, i setter per la classe del modello Account restituiscono l'oggetto, quindi possiamo concatenare le chiamate al nuovo oggetto Account. Utilizzeremo anche il numero casuale generato durante la creazione dell'account AdWords 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 accennato nell'introduzione a questo passaggio, poiché abbiamo già l'ID AdWords del nuovo account gestito, possiamo aggiungere questo ID all'elenco di AdwordsLinks per il nuovo subaccount. Quando viene creato il nuovo subaccount, questo collegamento viene richiesto automaticamente ed è disponibile nell'API AdWords.

Creare il nuovo subaccount

Nell'API Content, chiamiamo il metodo accounts() dell'oggetto sessione per accedere al servizio Accounts, quindi chiamiamo direttamente il metodo insert() anziché configurare un oggetto operazione. Questo metodo accetta due argomenti: l'ID dell'account multi-cliente in cui 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 del nuovo subaccount. Sovrascriviamo l'oggetto Account originale perché la versione restituita include un'informazione importante: l'ID del nuovo subaccount. Lo stampiamo nell'output della nostra soluzione, in modo da poterla eseguire e verificare che il nuovo subaccount esista in Merchant Center.

Provare

Come prima, prova a eseguire la soluzione. Se utilizzi Maven dalla riga di comando:

mvn compile

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

Se tutto va bene, non dovresti visualizzare errori e questa volta vedrai gli ID del nuovo account AdWords e del nuovo account Merchant Center. Controlla il Merchant Center per il tuo account multi-cliente per visualizzare il nuovo subaccount.

Nota: come per AdWords, ogni esecuzione della soluzione genererà nuovi account Merchant Center. Puoi eliminare i subaccount creati tramite il Merchant Center al termine dell'esecuzione della soluzione.

7. Accettare il collegamento dall'account AdWords

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

Accedere a CustomerService

Come prima, utilizzeremo la classe AdWordsServices per ottenere un client per CustomerService. Tuttavia, prima di creare il client, modifichiamo l'oggetto sessione AdWords in modo che gli utilizzi futuri operino sul nuovo account gestito anziché sull'account amministratore. Dopotutto, 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);

Specificare il collegamento richiesto

Come quando abbiamo creato un nuovo account AdWords, creeremo un ServiceLink oggetto che contiene le impostazioni del collegamento e poi un ServiceLinkOperation oggetto che descrive l'operazione desiderata. In questo caso, vogliamo prendere il collegamento del servizio in attesa a un account MERCHANT_CENTER e SETlo su ACTIVE. Per l'impostazione serviceLinkId, utilizzeremo l'ID dell'account Merchant Center che abbiamo appena creato, poiché viene utilizzato per l'ID del collegamento del 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 prima, accetta un array di operazioni di collegamento del servizio. Questa volta, il metodo restituisce direttamente un elenco di collegamenti del servizio (eventualmente modificati), quindi stamperemo il risultato della nostra soluzione scorrendo questo elenco. Naturalmente, poiché abbiamo specificato una sola operazione, ci aspettiamo che nell'output venga stampato un solo collegamento.

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

Provare

Come prima, prova a eseguire la soluzione. Se utilizzi Maven dalla riga di comando:

mvn compile

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

Se tutto va bene, non dovresti visualizzare errori e questa volta vedrai anche una nota che indica che il collegamento del servizio è stato aggiornato per essere attivo. Controlla AdWords e Merchant Center e verifica che gli account siano effettivamente collegati.

8. Variazioni sul tema

Congratulazioni per aver completato il codelab. Ora che hai una soluzione completamente funzionante, esaminiamo alcuni esempi di come potresti modificarla o estenderla per utilizzare più API che hai visto in questo codelab.

Credito extra: aggiornare un account Merchant Center esistente per richiedere un collegamento AdWords

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

Nota: ti consigliamo di utilizzare il metodo Accounts.update o Accounts.patch. Prova una versione con ciascuna per capire la differenza.

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

Credito extra: verificare la creazione del collegamento recuperando le informazioni dell'account AdWords e Merchant Center

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

Nota: per l'API Content, ti consigliamo di esaminare il metodo Accounts.get. Per AdWords, ti consigliamo di utilizzare il getServiceLinks metodo dell'oggetto CustomerServiceInterface.

Il mondo è tuo

Se ti vengono in mente altre modifiche che potresti apportare, provale. Se hai bisogno di codice di riferimento per le tue idee, consulta gli esempi di Google Shopping e la directory examples nel codice sorgente della libreria client Java di Google Ads.