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

A marzo 2019 abbiamo rilasciato la versione 2.1 dell'API Content for Shopping e ad aprile 2021 abbiamo annunciato che la versione 2 non sarebbe più supportata a partire dal 30 settembre 2021. La versione v2 è stata ritirata. Esegui subito la migrazione alla versione 2.1.

Esegui la 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 in modo da tenere conto delle modifiche che non sono più supportate introdotte nella versione 2.1.

Aggiorna le 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, devi utilizzare:

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

Per la versione 2.1, aggiorna l'URL in:

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 all'API.

Apporta le modifiche desiderate

Oltre ad aggiornare gli URL per le chiamate API, devi anche aggiornare la tua applicazione in modo da tenere conto di diverse modifiche non compatibili introdotte nella versione 2.1. Esamina le seguenti sezioni e aggiorna la tua applicazione, se necessario.

1. Aggiorna le integrazioni con il servizio inventory

Il servizio inventory v2 è 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.

  • La risorsa reviewsUrl è stata rimossa.

  • 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 replaced 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 un ritardo di alcuni minuti prima che un prodotto inserito possa essere recuperato tramite products.get o products.list.

  • Non è più garantito che il valore offerId restituito sia uguale al valore offerId inserito. La versione 2.1 rimuove gli spazi iniziali e finali inofferId e unisce più caratteri di spaziatura in uno. Questa modifica non influisce sui valori offerId conformi alla sintassi consigliata offerId.

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

  • Le risposte di 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 passa il valore del nuovo campo productId.

  • Il parametro includeInvalidInsertedItems è stato rimosso. Ora il valore productId di ogni prodotto viene restituito indipendentemente dal fatto che il prodotto sia valido o meno.

  • 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

  • I seguenti campi target sono stati sostituiti:

    • 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 i dati fiscali perché vengono calcolati automaticamente. Se l'ordine viene evaso in uno stato con un Marketplace Fairness Act (MFA) o un'altra legge simile, le chiamate che includono i dati fiscali non vanno a buon fine. Se l'ordine viene evaso in uno stato diverso dalla verifica in due passaggi, l'imposta viene calcolata in base alle impostazioni configurate in Merchant Center. Se non è configurata, l'imposta calcolata è pari a 0.

  • I campi InStoreRefundLineItem e ReturnRefundLineItem amountPretax e amountTax sono stati sostituiti da priceAmount e taxAmount, rispettivamente. 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 ora sono 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 ora viene 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 daorderreturns.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 (del commerciante, del cliente e di Google) nei campi relativi a invoiceSummary e ai caricamenti promozionali.

8. Rimuovere le funzionalità non incluse nella versione 2.1

Diverse altre funzionalità sono state rimosse dall'API Content nella versione 2.1. Esamina l'elenco seguente e aggiorna la tua applicazione, se necessario:

  • Il formato XML non è più supportato. Per ulteriori informazioni sul passaggio a JSON, consulta Ritiro del supporto di 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.

Testa la migrazione

Per ulteriori informazioni su come testare le modifiche alle tue 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 in grado di interrompere il servizio:

  • Nuovi servizi:

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

    • Il nuovo servizio orderreturns semplifica la gestione di Acquista su Google (in precedenza 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 e apportare aggiornamenti successivi per risolvere i problemi tramite le regole del feed in Merchant Center, proprio come faresti con i feed gestiti al di fuori dell'API Content.

    • products.update è stato aggiunto per consentirti di apportare aggiornamenti a un insieme scelto di campi del prodotto. Per ulteriori informazioni sulle possibili modalità di 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 ora sono ricorsivi, il che elimina la necessità di gruppi personalizzati.

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