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

A marzo 2019 abbiamo rilasciato 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 v2 è stata ritirata. Esegui immediatamente la migrazione alla versione 2.1.

Eseguire la migrazione dell'applicazione

La migrazione dalla versione 2 alla 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.

Aggiorna le chiamate API per utilizzare gli endpoint v2.1

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

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

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.

Apporta le modifiche desiderate

Oltre ad aggiornare gli URL per le chiamate API, devi anche aggiornare la tua applicazione per tenere conto di diverse modifiche sostanziali introdotte nella versione 2.1. Esamina le seguenti sezioni e aggiorna la tua applicazione in base alle esigenze.

1. Aggiornare le integrazioni con il servizio inventory

Il servizio v2 inventory è stato rimosso e la funzionalità equivalente è disponibile con le seguenti funzionalità v2.1:

2. Aggiorna le chiamate al servizio accounts

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

  • reviewsUrl è stato rimosso.

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

3. Aggiorna 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

  • Sono stati rimossi i seguenti campi:

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

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

  • Ora è previsto un ritardo di alcuni minuti prima che un prodotto inserito possa essere recuperato tramite products.get o products.list.

  • Non è più garantito che il offerId restituito sia uguale al offerId di input. La versione 2.1 rimuove gli spazi vuoti iniziali e finali in offerId e unisce più caratteri di spaziatura 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 valori sono consentiti solo i seguenti caratteri: +, -, . e cifre (ad es. 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 v2 includeAttributes è deprecata. Utilizza invece products.get con ProductId per visualizzare le informazioni complete sul prodotto.

4. Aggiorna le chiamate al servizio productstatuses

  • L'attributo product è stato rimosso, insieme al parametro includeAttributes. Per recuperare gli attributi del prodotto corrispondenti a uno stato, utilizza il servizio products e trasmetti 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, una stringa che può essere approved, disapproved o pending.

  • dataQualityIssues è stato sostituito da itemLevelIssues.

5. Aggiorna le chiamate al servizio datafeeds

  • Sono stati sostituiti i seguenti campi di destinazione:

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

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

6. Aggiorna le chiamate ai servizi orders e TestOrders

  • Nella versione 2.1, le chiamate non devono includere dati fiscali perché questi vengono calcolati automaticamente. Se l'ordine viene evaso in uno stato con un Marketplace Fairness Act (MFA) o simile, le chiamate che includono 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, la tassa calcolata è pari a 0.

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

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

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

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

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

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

  • I campi CancelLineItem amount, amountPretax e amountTax nella richiesta sono stati rimossi. 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 v2orders.returnlineitem e orders.refund vengono 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. Aggiorna le chiamate al servizio orderinvoice

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

  • Sono stati rimossi i saldi (commerciante, cliente, Google) in invoiceSummary e i campi correlati all'addebito della promozione.

8. Rimuovere le funzionalità non incluse nella versione 2.1

Nella versione 2.1 dell'API Content sono state rimosse diverse altre funzionalità. Esamina il seguente elenco e aggiorna l'applicazione in base alle esigenze:

  • XML non è più supportato. Per ulteriori informazioni sul passaggio a JSON, consulta Ritiro del supporto XML nell'API Content 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 Testare gli utilizzi dell'API Content for Shopping. Se riscontri problemi durante il test degli aggiornamenti, puoi contattarci.

Modifiche aggiuntive nella versione 2.1

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

  • Nuovi servizi:

    • Il nuovo servizio localinventory ti consente di apportare aggiornamenti ai prodotti locali (al posto del servizio inventory 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 ai 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 eseguire aggiornamenti successivi per risolvere i problemi tramite le regole del feed in Merchant Center, proprio come faresti con i feed gestiti all'esterno dell'API Content.

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

    • I valori non validi per i seguenti attributi non attivano più 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.

    • Ora gli attributi personalizzati hanno un campo groupValues oltre al campo value originale. Deve essere impostato esattamente uno dei campi.