Gestione dei prodotti
L'API contenuto è un'API RESTful che usa la risorsa Prodotti per gestire le offerte di prodotti nell'archivio Microsoft Merchant Center (MMC).
Di seguito è riportato l'URI di base usato per chiamare l'API Contenuto.
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/
Ogni richiesta HTTP deve includere il token di accesso OAuth dell'utente e il token di sviluppo. Per specificare il token di accesso dell'utente, impostare l'intestazione AuthenticationToken . Per specificare il token di sviluppo, impostare l'intestazione DeveloperToken .
Se si gestiscono cataloghi per conto di altri clienti, è necessario impostare:
- L'intestazione CustomerId all'ID cliente del cliente di cui si sta gestendo il negozio.
- L'intestazione CustomerAccountId sull'ID account di uno degli account del cliente gestiti dall'utente (non importa quale account gestito).
Per impostazione predefinita, l'API Contenuto usa oggetti JSON per rappresentare l'offerta del prodotto. Per usare XML, impostare il parametro di query alt su XML.
Per informazioni dettagliate sull'uso della risorsa Products, vedere le sezioni seguenti.
- Ottenere un'offerta di prodotto dal negozio
- Ottenere un elenco di offerte di prodotti dal negozio
- Eliminazione di un'offerta dallo store
- Aggiunta e aggiornamento di un'offerta di prodotto
- Uso dell'elaborazione batch
Ottenere un'offerta di prodotto dal negozio
Per ottenere un'offerta di prodotto specifica dallo store, aggiungere il modello seguente all'URI di base.
{mmcMerchantId}/products/{productUniqueId}
Impostare sull'ID {mmcMerchantId} dello store MMC e sull'ID{productUniqueId} prodotto completo (ad esempio Online:en:US:Sku123), non sul valore offerId del prodotto. Poiché l'ID prodotto fa distinzione tra maiuscole e minuscole, usare l'ID restituito dall'API quando è stato aggiunto il prodotto.
Inviare una richiesta HTTP GET all'URL risultante. Se il prodotto è stato trovato, la risposta contiene un oggetto Product che contiene l'offerta.
Se è stato inserito un prodotto con lo stesso ID in più cataloghi, il servizio ne restituisce solo uno, quale prodotto e da quale catalogo non è determinato. Per questo motivo, non è consigliabile inserire un prodotto con lo stesso ID prodotto in più cataloghi.
Per un esempio di codice che illustra come ottenere un'offerta di prodotto, vedere Gestione dell'esempio di codice dei prodotti.
Ottenere un elenco di offerte di prodotti dal negozio
Per ottenere un elenco delle offerte di prodotto presenti nello store, aggiungere il modello seguente all'URI di base.
{mmcMerchantId}/products
Impostare l'ID {mmcMerchantId} archivio MMC.
Per scorrere l'elenco delle offerte, usare i parametri di query max-results e start-token . Nella prima chiamata impostare max-results sul numero massimo di offerte che il servizio deve restituire. Il numero massimo di offerte che il servizio può restituire è 250. Il valore predefinito è 25. Inviare una richiesta HTTP GET all'URL risultante. Di seguito viene illustrato un esempio della richiesta.
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250
Se l'archivio contiene offerte, la risposta contiene un oggetto Product che contiene fino al numero di offerte richiesto.
Se sono disponibili altre offerte, la risposta include il nextPageToken campo (vedere Prodotti). Il nextPageToken campo contiene il valore del token usato per impostare il start-token parametro su nella richiesta elenco successiva. Di seguito viene illustrato un esempio che usa il token .
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250&start-token=DFSos893j...
Per un esempio di codice che illustra come ottenere un elenco di offerte di prodotti, vedere Gestione dell'esempio di codice dei prodotti.
Eliminazione di un'offerta dallo store
Per eliminare un'offerta di prodotto specifica dallo store, aggiungere il modello seguente all'URI di base.
{mmcMerchantId}/products/{productUniqueId}
Impostare sull'ID {mmcMerchantId} dello store MMC e sull'ID{productUniqueId} prodotto completo (ad esempio Online:en:US:Sku123), non sul valore offerId del prodotto. Poiché l'ID prodotto fa distinzione tra maiuscole e minuscole, usare l'ID restituito dall'API quando è stato aggiunto il prodotto.
Inviare una richiesta HTTP DELETE all'URL risultante. Se il prodotto è stato trovato, viene eliminato.
Se è stato inserito un prodotto con lo stesso ID prodotto in più cataloghi, il servizio li elimina tutti. Non inserire un prodotto con lo stesso ID prodotto in più cataloghi.
Per un esempio di codice che illustra come eliminare un'offerta di prodotto, vedere Gestione dell'esempio di codice dei prodotti.
Aggiunta e aggiornamento di un'offerta di prodotto
L'aggiunta o l'aggiornamento di un'offerta è un'operazione di inserimento. Poiché un aggiornamento è un'operazione di inserimento, è necessario includere tutti i campi dell'offerta nella richiesta. non è possibile aggiornare un singolo campo.
Per inserire un'offerta di prodotto, aggiungere il modello seguente all'URI di base.
{mmcMerchantId}/products
Impostare l'ID {mmcMerchantId} archivio MMC.
L'invio di una richiesta HTTP POST all'URL risultante scrive l'offerta nel catalogo archivio predefinito. Per scrivere l'offerta in un catalogo specifico, includere il parametro di query bmc-catalog-id .
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?bmc-catalog-id=123456
Se il prodotto è stato inserito, la risposta contiene un oggetto Product . L'oggetto Product include l'ID prodotto usato per ottenere ed eliminare l'offerta.
Un'offerta deve includere i campi seguenti:
L'API channelusa , contentLanguage, targetCountrye offerId per generare l'ID prodotto. Poiché questi campi vengono usati per generare l'ID, è possibile non aggiornarli. L'ID prodotto fa distinzione tra maiuscole e minuscole; l'ID usa la stessa combinazione di maiuscole e minuscole usata per specificare channel, contentLanguage, targetCountrye offerId.
Attenzione
Assicurarsi di usare la stessa combinazione di maiuscole e minuscole per channel, contentLanguage, targetCountrye offerId perché è possibile aggiungere lo stesso prodotto più volte se il contenitore è diverso.
Se il produttore ha assegnato valori, sono necessari anche i campi seguenti.
È necessario specificare i valori, se noti. Se non si specifica nessuno di essi, è necessario impostare il campo identifierExistssu false. Il valore predefinito è true.
Se il prodotto è noto per avere questi identificatori e non li si specifica, MMC accetta il prodotto per il momento, ma l'oggetto Product nella risposta include il warnings campo . È consigliabile controllare sempre se il warnings campo esiste e correggere tutti i problemi identificati.
Oltre ai campi obbligatori, è necessario specificare anche la data e l'ora di scadenza dell'offerta (vedere expirationDate). Per impostazione predefinita, l'offerta scade 30 giorni dalla data e dall'ora in cui viene scritta nell'archivio o nel catalogo. È consigliabile tenere traccia dei prodotti che si avvicinano alla scadenza e prima della scadenza aggiornare la data di scadenza o semplicemente aggiornare il prodotto (non è necessario aggiornare nessuno dei campi del prodotto), che estende automaticamente la data di scadenza per altri 30 giorni. Se si imposta in modo esplicito la data di scadenza, è necessario impostare manualmente una nuova data di scadenza. l'aggiornamento del prodotto non estenderà automaticamente la data di scadenza di altri 30 giorni in questo caso.
Tutti gli altri campi sono considerati facoltativi; tuttavia, è necessario specificare il numero necessario per descrivere accuratamente il prodotto.
Nota
L'oggetto Product deve includere solo i campi impostati su valori. Non includere campi Null nell'oggetto Product . Ad esempio, non includere "adult":null.
Microsoft non usa tutti i Product campi. Per un elenco dei campi che l'API accetta ma non usa, vedere Quali attributi di Google è possibile usare? Tutti gli altri campi usati da Microsoft vengono usati per filtrare i prodotti durante la pubblicazione di annunci di prodotti.
Se si specifica un campo sconosciuto per l'API Contenuto, il servizio ignora il campo.
Quando si inserisce un'offerta, il servizio esegue convalide di base sull'offerta e restituisce errori e avvisi in base alle esigenze. Se si verifica un errore, la risposta contiene un ErrorResponse oggetto . Se si verificano avvisi, la risposta contiene un Product oggetto e il warnings campo elenca gli avvisi.
Se l'offerta supera le convalide di base, viene sottoposta a convalide e revisioni offline, ad esempio recensioni editoriali, che possono richiedere fino a 36 ore. L'offerta non verrà usata fino al completamento di tutte le convalide e le verifiche. Per determinare lo stato di un'offerta, usare la risorsa Stato .
Si noti che l'API non fornisce controlli di concorrenza, ad esempio ETag. Se due app tentano di aggiungere o aggiornare lo stesso prodotto, vince l'ultima.
Un'offerta visualizzata in un annuncio di prodotto include il prezzo, il titolo, il nome del negozio (o sellerName, se specificato), il collegamento alla pagina Web che contiene altre informazioni sul prodotto e un'immagine del prodotto.
Per i prodotti di abbigliamento disponibili in più colori, modelli o materiali, creare un prodotto per ogni variante e usare il campo itemGroupId per raggruppare tutte le varianti del prodotto.
Per un esempio di codice che illustra come inserire un'offerta di prodotto, vedere Gestione dell'esempio di codice dei prodotti.
Uso dell'elaborazione batch
Se si elaborano più offerte di prodotti, è consigliabile usare la funzionalità di elaborazione batch dell'API. Questa funzionalità consente di elaborare più inserimenti, ottiene ed eliminazioni in una singola richiesta. L'elaborazione di più offerte nella stessa richiesta è più efficiente rispetto all'invio di una richiesta separata per ogni offerta. Il costo sostenuto per l'elaborazione di una singola richiesta è ripartito tra le migliaia di offerte nella richiesta batch anziché sostenere tale costo per ogni singola richiesta.
Non inserire, ottenere o eliminare lo stesso prodotto nella stessa richiesta.
Per inviare una richiesta batch, aggiungere il modello seguente all'URI di base.
{mmcMerchantId}/products/batch
Impostare l'ID {mmcMerchantId} archivio MMC.
L'invio di una richiesta HTTP POST all'URL risultante applica le operazioni di inserimento al catalogo archivio predefinito. Per applicare le offerte a un catalogo specifico, includere il parametro di query bmc-catalog-id .
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products/batch?bmc-catalog-id=123456
Il corpo dell'oggetto POST è un oggetto Batch che contiene una matrice di oggetti Item . Per tutte le operazioni, impostare i batchIdcampi e merchantIdmethod . è batchId un ID definito dall'utente usato per identificare l'elemento batch nella risposta; è l'ID merchantId archivio e è l'operazione method da eseguire , ad esempio inserimento, eliminazione o recupero.
Se method è insert, impostare il product campo su un oggetto Product che contiene l'offerta da aggiungere o aggiornare. In caso contrario, se method è un get o delete, impostare productIdsull'ID completo dell'offerta che si vuole ottenere o eliminare.
Le dimensioni del corpo di una richiesta batch non possono superare i 4 MB. Se il corpo supera i 4 MB, la risposta restituisce il codice di stato HTTP 413. A seconda delle dimensioni di ogni offerta (il numero di campi specificati), è possibile inviare tra 2.000 e 6.000 offerte. Se comprimi il corpo, puoi inviare il numero massimo di offerte, ovvero 12.000 (a seconda delle dimensioni).
Per comprimere il corpo, usare solo la compressione GZip e impostare l'intestazione Content-Encoding della richiesta su gzip.
Il servizio elabora ogni elemento nel batch. La risposta contiene un Batch oggetto che contiene ogni Item oggetto presente nella richiesta. Si noti che non esiste alcuna garanzia che l'ordine degli elementi nella risposta sia nello stesso ordine degli elementi nella richiesta.
Per le operazioni di inserimento, l'elemento include solo i batchId campi e product . Il product campo contiene la stessa offerta inviata nella richiesta, ma include anche l'ID prodotto completo. Se si verifica un errore o un avviso, l'elemento include i batchIdcampi , methode error . Il error campo contiene i motivi per cui l'inserimento non è riuscito o gli avvisi relativi ai problemi relativi all'offerta che è necessario correggere.
Per le operazioni get, l'elemento include i batchId campi e product . Il product campo contiene l'offerta richiesta. Se il prodotto non viene trovato, l'oggetto non includerà il product campo .
Per le operazioni di eliminazione, l'elemento include solo il batchId campo . Non è possibile indicare se l'offerta esiste ed è stata eliminata.
Per un esempio di codice che illustra come usare l'elaborazione batch, vedere Creazione di una richiesta Batch.