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 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 o versioni successive
• Maven
• Il codice di esempio
• Un editor di testo (è consigliato un IDE che supporti i progetti Maven come Eclipse o IntelliJ)

2. Preparazione

Scarica il codice

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

Scarica il codice sorgente

Estrai il file ZIP scaricato. Verrà scompattata una cartella principale (shopping-account-linking-master), che contiene un progetto Maven e tutte le risorse necessarie. Le seguenti sottodirectory sono particolarmente importanti:

• src/main/java è la directory principale del progetto Maven e contiene uno scheletro di codice da utilizzare.
• src/main/java/solution contiene la soluzione finale.

Installa i pacchetti e la compilazione richiesti

Se utilizzi un IDE compatibile con Maven come Eclipse o IntelliJ, puoi importare la cartella estratta come progetto Maven e 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 scompattato (shopping-account-linking-master):

mvn compile

3. Configura l'autenticazione

Per questo passaggio non scriveremo codice, ma configureremo i file contenenti 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, la configurazione dovrebbe essere già stata eseguita. In caso contrario, segui i passaggi da 1 a 3 per iniziare a utilizzare la libreria client delle API Google Ads per Java.

Configura 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 extra:
2. Seleziona Autenticazione e poi fai clic sul pulsante + blu:
3. Dopo aver accettato i Termini di servizio della piattaforma Google Cloud e delle API Google, il browser scaricherà automaticamente un file JSON contenente la chiave del nuovo account di servizio.

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

Prova

Ora che hai i token di autenticazione nei posti giusti, prova a eseguire i sample. Se utilizzi Maven nella 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), esegui la ricompilazione prima di eseguire i sample per copiare le risorse modificate nel target.

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

Se ricevi un messaggio di errore relativo alla mancata fornitura di oggetti sessione, significa che i token di autenticazione sono presenti e funzionano correttamente. In caso contrario, il messaggio di errore che visualizzi dovrebbe indicare quali credenziali non sono riuscite a funzionare e quale file correggere.

Importante: il framework che abbiamo fornito presuppone che l'account di servizio dell'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 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, che poi utilizzeremo per creare l'oggetto ShoppingContent appropriato. Fortunatamente, tutto ciò che serve per costruire il primo è già disponibile nello scheletro del codice, quindi dobbiamo solo riunirlo 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 negli esempi di codice successivi esistono già nello scheletro del codice. Cercale per vedere dove devono essere aggiunte queste linee.

Inoltre, ometteremo eventuali istruzioni di importazione necessarie per le classi dell'API AdWords e dell'API Content che utilizziamo in questi snippet. Se non utilizzi un IDE che può aggiungere automaticamente le importazioni corrette, controlla il codice nel pacchetto solution per individuare 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

Allo stesso modo, esiste una classe AdWordsSession.Builder per la creazione di oggetti AdWordsSession. La differenza principale è che, anziché impostare le opzioni di configurazione direttamente nel generatore, utilizzeremo il metodo fromFile() per caricarle dal file ads.properties configurato nel passaggio precedente.

SolutionRunner.java

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

Prova

Se esegui il progetto Maven dalla riga di comando, utilizzeremo gli stessi comandi dell'ultima sezione per ricostruirlo ed eseguirlo:

mvn compile

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

Questa volta non dovresti ricevere alcun errore, anche se non otterrai alcun output interessante. Lo aggiungeremo quando chiamiamo 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, esamineremo e creeremo gli account da collegare. Inizieremo con AdWords e creeremo un account di prova nel nostro account amministratore.

Nota:tutti gli snippet di codice in questa sezione vengono aggiunti nello stesso punto del codice scheletro nell'ordine presentato. Per questo motivo, mostreremo solo il commento (// TODO...) che indica dove posizionarli nel primo. Pertanto, in questo e nei passaggi successivi, se vedi snippet di codice senza un commento introduttivo, questi vanno subito 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 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 contenente le impostazioni del nuovo account. Creeremo un account di test per questo codelab, impostando la valuta su USD e il fuso orario sulla 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 è solo per poter associare l'account AdWords che creeremo qui all'account Merchant Center che creeremo in un secondo momento, in modo da poterli ispezionare visivamente una volta completata la nostra soluzione e assicurarci che siano stati effettivamente collegati.

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

Poi eseguiremo 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 uso futuro e lo stamperemo in modo da poterlo vedere nell'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);

Prova

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 il nuovo account elencato anche lì.

Nota:a questo punto, ogni esecuzione della soluzione genererà nuovi account. Puoi annullare gli account AdWords creati tramite il sito AdWords dopo aver completato l'esecuzione della soluzione. Dopotutto, il nostro schema di denominazione di questi account consente di capire facilmente quali sono stati creati dal nostro codice.

6. Creare un nuovo subaccount Merchant Center

In questo passaggio creeremo il subaccount Merchant Center da collegare all'account AdWords creato nell'ultimo passaggio. Invece di richiedere un collegamento separatamente dopo aver creato il subaccount, possiamo richiederlo durante la creazione, poiché abbiamo già l'ID dell'account AdWords corrispondente.

Specifica le impostazioni per il nuovo subaccount

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

Crea il nuovo subaccount

Nell'API Content, chiamiamo il metodo accounts() dell'oggetto sessione per accedere al servizio Accounts e poi 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 contenente 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 contenente le impostazioni del nuovo subaccount. Sovscriviamo 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 poter eseguire la nostra soluzione e verificare che il nuovo subaccount esista in Merchant Center.

Prova

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 sia del nuovo account AdWords sia del nuovo account Merchant Center. Per visualizzare il nuovo subaccount, accedi a Merchant Center per il tuo account multi-cliente.

Nota:come per AdWords, ogni esecuzione della soluzione ora genererà nuovi account Merchant Center. Puoi eliminare i subaccount creati tramite Merchant Center dopo aver eseguito la soluzione.

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 completeremo la procedura utilizzando l'API AdWords per accettare il collegamento richiesto.

Accedi 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 vengano eseguiti 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 oggetto ServiceLink contenente le impostazioni del collegamento e un oggetto ServiceLinkOperation che descriva l'operazione desiderata. In questo caso, vogliamo trasferire il collegamento del servizio in attesa a un account MERCHANT_CENTER e SET a ACTIVE. Per l'impostazione serviceLinkId, utilizzeremo l'ID dell'account Merchant Center che abbiamo appena creato, in quanto 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, richiede un array di operazioni di collegamento dei servizi. Questa volta il metodo restituisce direttamente un elenco di link ai servizi (eventualmente modificati), quindi stamperemo il risultato della nostra soluzione eseguendo un ciclo sull'elenco. Ovviamente, poiché abbiamo specificato una sola operazione, dovresti aspettarti che nell'output venga stampato un solo 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());
}

Prova

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 al servizio è stato aggiornato per essere attivo. Controlla AdWords e Merchant Center e verifica che gli account siano effettivamente collegati.

8. Variazioni su un tema

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

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

Nel codelab, abbiamo creato in modo intelligente l'account AdWords per 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 ad alterare il codice per creare prima l'account Merchant Center, poi 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 ciascuno 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 sarà disponibile, riceverai un errore HTTP 401 quando tenterai di accedervi o modificarlo. I Sample di Shopping contengono un esempio di utilizzo del backoff esponenziale per ripetere i metodi in AccountWorkflow.java, che utilizza il metodo retryFailures di BaseWorkflowSample.java.

Credito extra: verifica la creazione del collegamento recuperando i dati dell'account AdWords e Merchant Center

Al momento, l'applicazione considera un buon esito solo l'assenza di errori nelle chiamate all'API. Prova ad estendere l'esempio per controllare le informazioni sul collegamento per i nuovi account Merchant Center e Google Ads e verificare che il collegamento sia effettivamente attivo.

Nota: per quanto riguarda l'API Content, ti consigliamo di esaminare il metodo Accounts.get. Sul lato di AdWords, devi utilizzare il metodo getServiceLinks dell'oggetto CustomerServiceInterface.

Il mondo è tuo

Se pensi ad altre modifiche da apportare, provaci. Se hai bisogno di codice di riferimento per le tue idee, consulta i sample di Google Shopping e la directory examples nel codice sorgente della libreria client Java di Google Ads.