Eseguire la migrazione delle impostazioni della home page

L'API Merchant introduce una risorsa dedicata Homepage. Questa risorsa fornisce nuovi metodi per gestire la rivendicazione della home page, offrendo funzionalità che vanno oltre la classica API Content for Shopping.

L'accesso alle funzionalità del tuo negozio online è una procedura in due passaggi: prima devi verificare la proprietà, poi rivendicare il sito per il tuo account. Per completare il passaggio finale, utilizza accounts.homepage.claim.

Differenze principali

L'API Merchant apporta diverse modifiche relative alla home page rispetto all'API Content for Shopping:

• Risorsa dedicata: l'API Merchant fornisce una risorsa Homepage distinta (accounts.homepage) per tutte le operazioni relative alla home page. (Nell'API Content for Shopping, utilizzavi accounts.claimwebsite per eseguire l'azione di rivendicazione, l'URL della home page (website_url) faceva parte della risorsa Account e lo stato della rivendicazione (website_claimed) faceva parte della risorsa AccountStatus.)
• Metodi granulari: l'API Merchant offre metodi specifici per:
  • Recuperare i dettagli della home page: accounts.homepage.getHomepage
  • Aggiornare l'URI della home page: accounts.homepage.updateHomepage
  • Rivendicare la home page: accounts.homepage.claim
  • Annullare la rivendicazione della home page: accounts.homepage.unclaim L'API Content for Shopping utilizzava accounts.claimwebsite per l'azione di rivendicazione, accounts.update per impostare l'URL (e annullare effettivamente la rivendicazione impostando un URL vuoto) e accounts.get/accountstatuses.get per recuperare rispettivamente l'URL e lo stato della rivendicazione.
• Informazioni centralizzate: la risorsa Homepage dell'API Merchant contiene direttamente sia l'uri (URL della home page) sia lo stato claimed (rivendicato). Tutti i metodi che operano sulla risorsa Homepage restituiscono questa risorsa, fornendo un feedback immediato sullo stato attuale. Nell'API Content for Shopping, accounts.claimwebsite non restituiva lo stato aggiornato; erano necessarie chiamate separate.
• Annullamento esplicito della rivendicazione: nell'API Content for Shopping, l'annullamento della rivendicazione veniva in genere eseguito aggiornando Account.website_url a una stringa vuota. L'API Merchant fornisce un metodo homepage.unclaim dedicato.
• Sovrascrittura della rivendicazione: entrambe le API supportano un parametro overwrite durante la procedura di rivendicazione per rilevare una rivendicazione da un altro account se la proprietà può essere verificata.

Richieste

L'API Merchant utilizza endpoint RESTful distinti per gestire i diversi aspetti della home page.

Descrizione della richiesta	API Content for Shopping	API Merchant
Visualizzare i dettagli della home page	accounts.get (per leggere Account.website_url), accountstatuses.get (per leggere AccountStatus.website_claimed)	GET /accounts/v1/accounts/{account}/homepage
Aggiornare l'URI della home page	accounts.update (impostando Account.website_url)	PATCH /accounts/v1/accounts/{account}/homepage
Rivendicare o verificare di nuovo la home page	POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite (agiva su Account.website_url impostato utilizzando accounts.update)	POST /accounts/v1/accounts/{account}/homepage:claim
Annullare la rivendicazione della home page	accounts.update (impostando Account.website_url su una stringa vuota)	POST /accounts/v1/accounts/{account}/homepage:unclaim

Identificatori

L'identificazione delle risorse è stata semplificata nell'API Merchant.

Descrizione dell'identificatore	API Content for Shopping	API Merchant
Identificatore dell'account per l'accesso alle risorse	merchantId (account avanzato) e accountId (account secondario) nel percorso	account (parte del campo name, ad esempio accounts/{account_id}/homepage)
Identificatore della risorsa della home page	Non applicabile (implicito alla risorsa Account)	name: accounts/{account_id}/homepage (identifica la sotto-risorsa Homepage)

Metodi

Il metodo accounts.claimwebsite dell'API Content for Shopping, incentrato sull'azione di rivendicazione, fa ora parte di un insieme più ampio di funzionalità all'interno della risorsa Homepage dell'API Merchant.

Metodo dell'API Content for Shopping	Metodo dell'API Merchant	Disponibilità e note
accounts.claimwebsite	accounts.homepage.claim	Avvia o verifica di nuovo direttamente una rivendicazione del sito web. Agisce sull'uri impostato in precedenza utilizzando homepage.update. Include un parametro overwrite. Restituisce la risorsa Homepage con l'uri e lo stato claimed attuali.
accounts.get (per leggere Account.website_url), accountstatuses.get (per leggere AccountStatus.website_claimed)	accounts.homepage.getHomepage	Nuovo metodo dedicato per recuperare l'uri della home page attuale e il relativo stato claimed in una singola chiamata.
accounts.update (per impostare Account.website_url)	accounts.homepage.updateHomepage	Nuovo metodo dedicato per impostare o modificare l'uri della home page.
accounts.update (impostando Account.website_url su una stringa vuota come soluzione alternativa per annullare la rivendicazione)	accounts.homepage.unclaim	Nuovo metodo dedicato per annullare esplicitamente la rivendicazione di una home page.

Modifiche dettagliate dei campi

Il modo in cui le informazioni sulla home page sono strutturate e accessibili è cambiato in modo significativo, passando alla risorsa Homepage esplicita nell'API Merchant.

API Content for Shopping	API Merchant	Descrizione
merchantId (parametro del percorso per accounts.claimwebsite)	name (parametro del percorso per i metodi Homepage, formato: accounts/{account}/homepage)	La parte account della stringa name nell'API Merchant corrisponde a accountId dell'API Content for Shopping.
accountId (parametro del percorso per accounts.claimwebsite)	name (parametro del percorso per i metodi Homepage, formato: accounts/{account}/homepage)	L'identificatore dell'account specifico di cui viene gestita la home page.
overwrite (booleano nel corpo di ContentAccountsClaimwebsiteRequest e AccountsCustomBatchRequestEntry)	ClaimHomepageRequest.overwrite (booleano nel corpo della richiesta homepage.claim)	Facoltativo. Se true, tenta di rivendicare il sito web, rimuovendo potenzialmente una rivendicazione esistente da un altro account se la proprietà può essere verificata dall'account richiedente.
Account.website_url (campo nella risorsa Account, impostato utilizzando accounts.update, letto utilizzando accounts.get)	Homepage.uri (campo nella risorsa Homepage)	L'URI (URL) della home page del negozio. Nell'API Merchant, questo è un campo esplicito all'interno della risorsa Homepage. Viene impostato utilizzando accounts.homepage.updateHomepage e restituito da tutti i metodi Homepage.
AccountStatus.website_claimed (campo nella risorsa AccountStatus, letto utilizzando accountstatuses.get)	Homepage.claimed (campo booleano di sola lettura nella risorsa Homepage)	Indica se l'uri è rivendicato e verificato. Questo stato è disponibile direttamente nella risorsa Homepage restituita da tutti i metodi dell'API Merchant associati.
N/D	UpdateHomepageRequest.update_mask accounts.homepage.updateHomepage parametro del corpo della richiesta)	Una maschera di campo facoltativa per homepage.update per specificare i campi (ad es. uri) della risorsa Homepage da aggiornare.