Migrazione dalla versione 2.1 dell'API Content alla v2.1

A marzo 2019, abbiamo reso disponibile la versione 2.1 di Content API for Shopping e, ad aprile 2021, abbiamo annunciato che la versione 2 sarebbe stata ritirata il 30 settembre 2021. La versione 2 è stata ritirata. Esegui immediatamente la migrazione alla versione 2.1.

Migrazione dell'applicazione

La migrazione dalla versione 2 alla versione 2.1 prevede l'aggiornamento degli URL degli endpoint per chiamare le nuove versioni 2.1 e la modifica delle applicazioni per tenere conto delle modifiche che causano interruzioni introdotte nella versione 2.1.

Aggiornamento delle chiamate API per utilizzare gli endpoint della versione 2.1

Per effettuare chiamate alla versione 2.1, aggiorna le richieste in modo che utilizzino i nuovi endpoint della versione 2.1.

Ad esempio, per chiamare il metodo products.get con la versione 2, utilizzeresti:

GET https://shoppingcontent.googleapis.com/content/v2/merchantId/products/productId

Per la versione 2.1, aggiorna l'URL a:

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/productId

Per informazioni complete sui servizi e sugli endpoint della versione 2.1, consulta il Riferimento API.

Apportare le modifiche necessarie

Oltre ad aggiornare gli URL per le chiamate API, devi anche aggiornare l'applicazione per tenere conto di diverse modifiche che causano interruzioni introdotte nella versione 2.1. Esamina le seguenti sezioni e aggiorna l'applicazione, se necessario.

1. Aggiornare le integrazioni con il servizio inventory

Il servizio inventory della versione 2 è stato rimosso e funzionalità equivalenti sono disponibili con le seguenti funzionalità della versione 2.1:

2. Aggiornare le chiamate al servizio accounts

  • Le chiamate al metodo accounts.update nella versione 2.1 sovrascrivono completamente la accounts risorsa, anziché aggiornare solo i campi inclusi nella richiesta. Per evitare di eliminare i campi nella risorsa accounts, aggiorna le richieste di chiamata in modo che includano tutti i campi.

  • reviewsUrl è stato rimosso.

  • Lo stato del link inactive è stato rimosso per adsLinks, googleMyBusinessLink e youtubeChannelLinks.

3. Aggiornare le chiamate al servizio products

  • Gli attributi personalizzati non contengono più un tipo e un'unità. Le unità devono essere aggiunte al valore e i tipi devono essere rilevati automaticamente.

  • Il campo ripetuto productTypes ha sostituito sia productType sia additionalProductTypes.

  • I campi ripetuti includedDestinations e excludedDestinations hanno sostituito il campo ripetuto destinations.

  • I seguenti campi correlati ad AdWords sono stati rinominati:

    • adwordsGrouping -> adsGrouping
    • adwordsLabels -> adsLabels
    • adwordsRedirect -> adsRedirect

  • I seguenti campi sono stati rimossi:

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • Il parametro includeInvalidInsertedItems è stato rimosso. Nella versione 2.1, tutti i prodotti vengono restituiti per impostazione predefinita.

  • Ora è necessario attendere alcuni minuti prima che un prodotto inserito possa essere recuperato tramite products.get o products.list.

  • Non è più garantito che l'offerId restituito sia lo stesso dell'offerId di input. La versione 2.1 rimuove gli spazi vuoti iniziali e finali nell'offerId e unisce più spazi vuoti in uno solo. Questa modifica non influisce sui valori offerId conformi alla sintassi offerId consigliata.

  • I prezzi vengono ora convalidati prima dell'inserimento del prodotto. Nella stringa di valore sono consentiti solo i seguenti caratteri: +, -, ., e cifre (ovvero 0-9). Le virgole non sono più accettate.

  • Le risposte a una chiamata products.insert o products.update contengono solo i seguenti attributi:

    • channel
    • contentLanguage
    • id
    • offerId
    • feedLabel

  • L'opzione includeAttributes della versione 2 è obsoleta. Utilizza invece products.get con ProductId per visualizzare le informazioni complete sul prodotto.

4. Aggiornare le chiamate al servizio productstatuses

  • L'attributo product è stato rimosso, insieme al parametro includeAttributes. Per recuperare gli attributi del prodotto corrispondente a uno stato, utilizza il servizio products e passa il valore del nuovo campo productId.

  • Il parametro includeInvalidInsertedItems è stato rimosso. Il productId di ogni prodotto viene ora restituito indipendentemente dalla validità del prodotto.

  • I campi intention, approvalStatus e approvalPending in destinationStatuses sono stati sostituiti da status, che è una stringa che può essere `approved`, `disapproved` o `pending`.approveddisapprovedpending

  • dataQualityIssues è stato sostituito da itemLevelIssues.

5. Aggiornare le chiamate al servizio datafeeds

  • I seguenti campi di destinazione sono stati sostituiti:

    • contentLanguage -> language
    • targetCountry -> country
    • intendedDestinations -> includedDestinations e excludedDestinations

  • I feed di dati con contentType = "product inventory update" sono stati rimossi.

6. Aggiornare le chiamate ai servizi orders e TestOrders

  • Nella versione 2.1, le chiamate non devono includere i dati fiscali perché vengono calcolati automaticamente. Se l'ordine viene evaso in uno stato con il Marketplace Fairness Act (MFA) o simili, le chiamate che includono i dati fiscali non vanno a buon fine. Se l'ordine viene evaso in uno stato non MFA, l'imposta viene calcolata in base alle impostazioni configurate in Merchant Center. Se non è configurata, l'imposta calcolata è 0.

  • I campi amountPretax e amountTax di InStoreRefundLineItem e ReturnRefundLineItem sono stati sostituiti rispettivamente da priceAmount e taxAmount. priceAmount può essere al netto o al lordo delle imposte, a seconda della località dell'ordine.

  • I campi carrier, shipmentId e trackingId di ShipLineItem nella richiesta sono stati spostati in shipmentInfos.

  • billingAddress e predefinedBillingAddress sono ora campi di primo livello rispettivamente in orders e TestOrder.

  • customer.explicitMarketingPreference è stato sostituito da customer.marketingRightsInfo.

  • Il campo netAmount è stato suddiviso in netPriceAmount e netTaxAmount.

  • shippingOption è stato sostituito da lineItems[].shippingDetails.

  • I campi amount, amountPretax, e amountTax in the request sono stati rimossi.CancelLineItem L'importo rimborsato viene ora calcolato automaticamente.

  • CustomBatch è stato rimosso.

  • Refund è stato rimosso. Utilizza invece refundOrder o refundItem.

  • Il campo paymentMethod è stato rimosso.

  • I metodi orders.returnlineitem e orders.refund della versione 2 sono stati sostituiti da orderreturns.creatOrderReturn e orderreturns.process.

  • I campi customer.email, channelType e lineItem.product.channel sono stati rimossi.

  • Il campo promotions è stato rimosso dal servizio TestOrder e il suo formato è stato modificato in Order.

7. Aggiornare le chiamate al servizio orderinvoice

  • I campi amountPretax e amountTax sono stati sostituiti rispettivamente da priceAmount e taxAmount. Il campo priceAmount può essere al netto o al lordo delle imposte, a seconda della località dell'ordine.

  • Sono stati rimossi i saldi (commerciante, cliente, Google) in invoiceSummary e i campi correlati agli addebiti promozionali.

8. Rimuovere le funzionalità non incluse nella versione 2.1

Nella versione 2.1 sono state rimosse diverse altre funzionalità di Content API. Esamina il seguente elenco e aggiorna l'applicazione, se necessario:

  • XML non è più supportato. Per ulteriori informazioni sul passaggio a JSON, consulta la sezione Ritiro del supporto XML in Content API for Shopping.

  • Il parametro dryRun è stato rimosso. Questa modifica si applica a tutte le chiamate API.

  • Tutti i metodi HTTP BATCH sono stati rimossi. Utilizza invece customBatch.

  • Il metodo patch è stato rimosso dai seguenti servizi:

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • Il servizio orderpayments è stato rimosso.

Testare la migrazione

Per ulteriori informazioni sul test delle modifiche alle applicazioni dopo la migrazione alla versione 2.1, consulta la sezione Testare gli utilizzi di Content API for Shopping. Se riscontri problemi durante il test degli aggiornamenti, puoi contattarci.

Ulteriori modifiche nella versione 2.1

Oltre alle modifiche che richiedono aggiornamenti, la versione 2.1 introduce anche diverse nuove funzionalità e modifiche che non causano interruzioni:

  • Nuovi servizi:

    • Il nuovo localinventory servizio ti consente di apportare aggiornamenti dei prodotti locali (al posto del inventory servizio nella versione 2).

    • Il nuovo servizio orderreturns semplifica la gestione di Acquista su Google (precedentemente noto come Shopping Actions) consentendoti di elaborare i resi senza dover utilizzare il servizio orders.

  • I feed supplementari ti consentono di apportare aggiornamenti parziali dei prodotti.

  • Ulteriori modifiche al servizio products:

    • Le richieste products.insert non segnalano più avvisi o errori non irreversibili. In questo modo, puoi inserire i prodotti ed effettuare aggiornamenti successivi per risolvere i problemi tramite le regole del feed in Merchant Center, proprio come faresti con i feed gestiti all'esterno di Content API.

    • È stato aggiunto products.update per consentirti di apportare aggiornamenti a un insieme di campi di prodotto selezionati. Per ulteriori informazioni sul possibile utilizzo, consulta la guida.

    • I valori non validi per i seguenti attributi non attivano più gli errori di inserimento e vengono restituiti come parte di itemLevelIssues dal servizio productstatus:

      • ageGroup
      • availability
      • condition
      • energyEfficiencyClass
      • gender
      • maxEnergyEfficiencyClass
      • minEnergyEfficiencyClass
      • sizeSystem
      • sizeType

    • Gli attributi personalizzati sono ora ricorsivi, il che elimina la necessità di gruppi personalizzati.

    • Gli attributi personalizzati ora hanno un campo groupValues oltre al campo value originale. È necessario impostare esattamente uno dei campi.