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 sarebbe stata ritirata il 30 settembre 2021. La versione v2 è terminata. Esegui subito la migrazione alla versione 2.1.

Esegui la migrazione della tua applicazione

La migrazione dalla v2 alla v2.1 comporta l'aggiornamento degli URL degli endpoint in modo che chiamino le nuove versioni v2.1 e la modifica delle applicazioni per tenere conto delle modifiche che provocano un errore introdotte nella versione 2.1.

Aggiorna le chiamate API per utilizzare gli endpoint v2.1

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

Ad esempio, per chiamare il metodo products.get con v2, 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 su servizi ed endpoint v2.1, consulta la documentazione di riferimento API.

Apporta le modifiche desiderate

Oltre ad aggiornare gli URL per le chiamate API, devi anche aggiornare l'applicazione per tenere conto di diverse modifiche che provocano errori introdotte nella v2.1. Esamina le seguenti sezioni e aggiorna la tua applicazione, se necessario.

1. Aggiorna le integrazioni con il servizio inventory

La versione 2 del servizio inventory è stata rimossa ed è disponibile una funzionalità equivalente con le seguenti funzionalità della versione 2.1:

2. Aggiorna le chiamate al servizio accounts

  • Le chiamate al metodo accounts.update nella v2.1 sovrascrivono completamente la risorsa accounts, invece di 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à. Al contrario, le unità devono essere aggiunte al valore e i tipi devono essere rilevati automaticamente.

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

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

  • I seguenti campi relativi 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, per impostazione predefinita vengono restituiti tutti i prodotti.

  • Ora c'è 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 corrisponda all'input offerId. La versione 2.1 taglia gli spazi vuoti iniziali e finali in offerId e unisce più spazi vuoti in uno solo. Questa modifica non influisce sui valori offerId conformi alla sintassi offerId consigliata.

  • Ora i prezzi vengono convalidati prima dell'inserimento del prodotto. Nella stringa del valore sono consentiti solo i seguenti caratteri: +, -, . e cifre (ad esempio 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 valore productId di ogni prodotto viene ora restituito a prescindere dalla validità del prodotto.

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

  • dataQualityIssues è stato sostituito da itemLevelIssues.

5. Aggiorna 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. Aggiorna le chiamate ai servizi orders e TestOrders

  • Nella versione 2.1, le chiamate non devono includere i dati fiscali perché i dati fiscali 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 andranno a buon fine. Se l'ordine viene evaso in uno stato non MFA, le imposte vengono calcolate in base alle impostazioni configurate in Merchant Center. Se non viene configurata, l'imposta calcolata è 0.

  • I campi InStoreRefundLineItem e ReturnRefundLineItem amountPretax e amountTax sono stati rispettivamente sostituiti da priceAmount e taxAmount. priceAmount può essere al lordo delle imposte 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 della richiesta sono stati rimossi. L'importo rimborsato viene ora calcolato automaticamente.

  • La risorsa CustomBatch è stata rimossa.

  • La risorsa Refund è stata rimossa. Usa invece refundOrder o refundItem.

  • Il campo paymentMethod è stato rimosso.

  • I metodi v2 orders.returnlineitem e orders.refund sono sostituiti dai metodi 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 è cambiato 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 delle imposte o al netto delle imposte, a seconda della località dell'ordine.

  • Saldi rimossi (commerciante, cliente, Google) nei campi invoiceSummary e relativi all'addebito della promozione.

8. Rimozione della funzionalità non inclusa nella versione 2.1

Nella versione 2.1 sono state rimosse diverse altre funzionalità dall'API Content. Controlla il seguente elenco e aggiorna la tua applicazione, se necessario:

  • Il formato XML non è più supportato. Per ulteriori informazioni sul passaggio a JSON, consulta la pagina Ritiro del supporto di XML nella Content API for Shopping.

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

  • Tutti i HTTP BATCH metodi sono stati rimossi. Usa invece il criterio 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 su come testare le modifiche alle applicazioni dopo la migrazione alla v2.1, consulta la pagina Test dell'utilizzo dell'API Content for Shopping. Se riscontri problemi durante il test degli aggiornamenti, puoi pubblicare il problema nel forum dell'API Content.

Ulteriori modifiche nella versione 2.1

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

  • Nuovi servizi:

    • Il nuovo servizio localinventory ti consente di aggiornare i prodotti locali (al posto del servizio inventory nella v2).

    • 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 eseguire aggiornamenti parziali sui 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 aggiornare un insieme specifico di campi di 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 ora sono 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.