Hub per sviluppatoriStato dell'APISupporto

Guida ai casi d'uso di Data Kiosk

How to use the Data Kiosk API.

Versione API: 2023-11-15

Cos'è l'API Data Kiosk?

L'API per i partner di vendita per Data Kiosk consente di inviare query GraphQL da una varietà di schemi per aiutare i partner di vendita a gestire le proprie attività.

Punti chiave

  • Data Kiosk può restituire un documento dati o un documento di errore nella risposta dell'operazione getQuery. Può inoltre non restituire alcun documento nel caso in cui la query sia stata inviata correttamente, ma non siano stati restituiti dati.
    • Il documento dati contiene l'output in formato JSONL quando una richiesta andata a buon fine viene elaborata con lo stato di elaborazione DONE .
    • Il documento di errore è in formato JSON e contiene il messaggio di errore quando la richiesta non è andata a buon fine con lo stato di elaborazione FATAL .
  • Il valore processingStatus di DONE senza errorDocumentId o dataDocumentId nella risposta dell'operazione getQuery indica che la richiesta è stata completata senza dati o che non sono presenti dati per l'intervallo di tempo specificato. Prova a inviare nuovamente la richiesta con parametri diversi.
  • L'API Data Kiosk non supporta la pianificazione delle query.
  • L'API Data Kiosk non supporta il backlogging delle query. Data Kiosk limita il numero di query simultanee non terminali per partner di vendita e per query GraphQL.

Tutorial: richiedere e filtrare i dati con una query GraphQL

Questo tutorial illustra come richiedere e filtrare i dati con una query GraphQL.

Prerequisiti:

Per completare questo tutorial avrai bisogno di:

  • Il ruolo appropriato per i dati richiesti. Per gli esempi riportati in questo tutorial si utilizzano i dati sulle vendite e sul traffico, per cui è richiesto il ruolo Brand Analytics.

Passaggio 1. Crea una richiesta di query

Crea una richiesta di query asincrona specificando una query GraphQL valida e conforme allo schema. I parametri di input della query possono essere modificati in base alle esigenze e i campi di risposta possono essere inclusi o meno, in qualsiasi ordine.

Effettua una chiamata all'operazione createQuery, specificando la query nel corpo:

Parametro del corpo

Nome Type Descrizione Obbligatorio
query string The GraphQL query that is compliant with the schema. A query can be at most 8,000 characters after unnecessary whitespace is removed. Refer to the schema to build your query.

Esempi di richieste

Esempio 1: creazione di una richiesta di query per salesAndTrafficByDate in modo da ottenere un sottoinsieme di campi nella risposta.

POST https://sellingpartnerapi-na.amazon.com/dataKiosk/2023-11-15/queries { "query": "{analytics_salesAndTraffic_2023_11_15{salesAndTrafficByDate(startDate:\"2023-01-01\" endDate:\"2023-10-31\" aggregateBy:DAY marketplaceIds:[\"ATVPDKIKX0DER\"]){endDate marketplaceId startDate traffic{averageOfferCount browserPageViews averageParentItems browserPageViewsB2B browserSessions}sales{averageSalesPerOrderItem{amount currencyCode}averageSalesPerOrderItemB2B{amount currencyCode}averageSellingPrice{amount currencyCode}claimsGranted refundRate unitsOrderedB2B unitsRefunded unitsShipped}}}}" }

Esempio 2: creazione di una richiesta di query per salesAndTrafficByAsin in modo da ottenere un sottoinsieme di campi nella risposta.

POST https://sellingpartnerapi-na.amazon.com/dataKiosk/2023-11-15/queries { "query": "{analytics_salesAndTraffic_2023_11_15{salesAndTrafficByAsin(startDate:\"2023-01-01\" endDate:\"2023-10-31\" aggregateBy:PARENT marketplaceIds:[\"ATVPDKIKX0DER\"]){childAsin endDate marketplaceId parentAsin sales{orderedProductSales{amount currencyCode}totalOrderItems totalOrderItemsB2B}sku startDate traffic{browserPageViews browserPageViewsB2B browserPageViewsPercentage browserPageViewsPercentageB2B browserSessionPercentage unitSessionPercentageB2B unitSessionPercentage}}}}" }

Risposta

Una risposta con esito positivo include la seguente proprietà:

Nome Type Descrizione
queryId string L'identificatore della query. Questo identificatore è univoco solo in combinazione con l'ID partner di vendita.

Esempio di risposta

{ "queryId": "012345678901" }

Passaggio 2. Conferma che l'elaborazione della query è stata completata

Dopo aver effettuato una chiamata all'operazione createQuery, Amazon riceve la richiesta e inizia a elaborare la query. Prima di continuare, è necessario confermare che l'elaborazione della query è stata completata. Per informazioni su come eseguire questa operazione, consulta Verificare che l'elaborazione della query sia completa.

Passaggio 3. Ottieni le informazioni necessarie per recuperare il risultato della query

Effettua una chiamata all'operazione getDocument per ottenere le informazioni necessarie per recuperare il documento con i risultati della query, tra cui un URL prefirmato per il documento. Se il documento è compresso, l'intestazione Content-Encoding mostrerà l'algoritmo di compressione. Tieni presente che la procedura è diversa dal modo in cui l'API Report fornisce informazioni sulla compressione.

Parametro del percorso

Nome Type Descrizione Obbligatorio
documentId string L'identificatore per il documento con i risultati della query. L'identificatore è univoco solo in combinazione con l'ID partner di vendita.

Esempio di richiesta

GET https://sellingpartnerapi-na.amazon.com/dataKiosk/2023-11-15/documents/DOC-b8b0-4226-b4b9-0ee058ea5760

Risposta

Una risposta con esito positivo include quanto segue:

Nome Type Descrizione
documentId string L'identificatore del documento di query. L'identificatore è univoco solo in combinazione con l'ID partner di vendita.
documentUrl string Un URL prefirmato che può essere utilizzato per recuperare il documento Data Kiosk. Questo URL scade dopo cinque minuti. Se il documento Data Kiosk è compresso, l'intestazione Content-Encoding indicherà l'algoritmo di compressione.

Esempio di risposta

{ "documentId": "DOC-b8b0-4226-b4b9-0ee058ea5760", "documentUrl": "https://d34o8swod1owfl.cloudfront.net/SampleResult%2BKey%3DSample%2BINITVEC%3D58+fa+bf+a7+08+11+95+0f+c1+a8+c6+e0+d5+6f+ae+c8" }

Salva il valore di documentUrl per utilizzarlo nel passaggio successivo.

Passaggio 4. Scarica il documento

È necessario scaricare il documento di query utilizzando le informazioni restituite nel passaggio 3.

Il codice di esempio seguente illustra come scaricare un documento di Data Kiosk. Usa il valore documentUrl ottenuto nel passaggio precedente come argomento per il parametro url del metodo download della classe DownloadExample.

Nota: è necessario mantenere sempre la crittografia dei dati a riposo. Il contenuto non crittografato del documento con i risultati della query non deve mai essere archiviato su disco, nemmeno temporaneamente, poiché il documento può contenere informazioni riservate. Il codice di esempio seguente dimostra questo principio:

// DownloadExample.java // This example is for use with the Selling Partner API for Data Kiosk, Version: 2023-11-15 import java.io.BufferedReader; import java.io.IOException; import java.io.InputStream; import java.io.InputStreamReader; import java.nio.charset.StandardCharsets; import com.squareup.okhttp.OkHttpClient; import com.squareup.okhttp.Request; import com.squareup.okhttp.Response; import com.squareup.okhttp.ResponseBody; /** * Example that downloads a Data Kiosk document. */ public class DownloadExample { public static void main(String[] args) { String url = "<URL from the getDocument response>"; DownloadExample obj = new DownloadExample(); try { obj.download(url); } catch (IOException e) { // Handle exceptions here. e.printStackTrace(); } } /** * Download the document from the given Amazon Simple Storage Service (Amazon S3) URL. * * @param url the signed Amazon S3 URL to retrieve the document from. * @throws IOException when there is an error reading the response. */ public void download(String url) throws IOException { OkHttpClient httpclient = new OkHttpClient(); Request request = new Request.Builder() .url(url) .get() .build(); Response response = httpclient.newCall(request).execute(); if (!response.isSuccessful()) { System.out.printf("Call to download content was unsuccessful with response code: %d and message: %s%n", response.code(), response.message()); return; } try (ResponseBody responseBody = response.body(); InputStream inputStream = responseBody.byteStream(); // Note: If the Data Kiosk document is compressed, the 'Content-Encoding' header will indicate the // compression algorithm. Most HTTP clients are capable of automatically decompressing downloaded files // based on the 'Content-Encoding' header. // More Information: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding // // The OkHttp client will automatically set the "Accept-Encoding" header and respect the // "Content-Encoding" header, so it is not required to unzip the stream. // For clients which do not automatically decompress, wrapping the stream in a GZIP stream may be // required, for example: // InputStream unzippedInputStream = new GZIPInputStream(inputStream); InputStreamReader inputStreamReader = new InputStreamReader(inputStream, StandardCharsets.UTF_8); BufferedReader reader = new BufferedReader(inputStreamReader)) { String line; while ((line = reader.readLine()) != null) { // Process line by line. System.out.println(line); } } } }

Questa pagina ti è stata utile?