Utilizzo dello strumento di verifica delle API di eBay

Le API di eBay sono un sistema avanzato che consente di richiamare dati direttamente dai server eBay e che si differenzia dai feed, i quali sono file autonomi che contengono riferimenti a oggetti su eBay. Il sito Web del programma degli sviluppatori eBay contiene uno strumento di verifica delle API con cui valutare i risultati delle chiamate API utilizzando i vari parametri disponibili. Questo strumento può essere utilizzato direttamente da sviluppatori o collaboratori per testare le chiamate API di base prima dell'integrazione sul sito Web da parte dello sviluppatore. Presentazione completa delle API http://developer.ebay.com/quickstartguide/default.aspx

Strumento di verifica delle API  https://developer.ebay.com/DevZone/build-test/test-tool/default.aspx

Impostazione di una chiamata API

Sulla parte sinistra della pagina dello strumento sono disponibili delle opzioni per determinare il tipo e la destinazione delle chiamate API. Di seguito vengono descritte le varie sezioni, i loro scopi e i casi di utilizzo.

Scelta dell'ambiente: Sandbox o Production L'ambiente Sandbox utilizza database di verifica che non contengono oggetti e dati correnti. L'ambiente Production utilizza invece i database correnti che contengono oggetti attualmente in vendita su eBay. Utilizzate Sandbox quando verificate le chiamate inviate a eBay, ad esempio quelle nelle API Trading. Dopo la verifica, potete passare a Production per implementarla. Utilizzate Production quando estraete informazioni, ad esempio quando cercate oggetti, categorie e venditori.

Selezione dell'insieme di chiavi Questa sezione viene compilata automaticamente dopo aver impostato le chiavi di sviluppo utilizzando la pagina dell'account dello sviluppatore.  https://developer.ebay.com/DevZone/account/default.aspx

Selezione delle API Sono disponibili diverse API per svolgere diverse funzioni. Le API Shopping e Finding servono a cercare oggetti in vendita. Le API Trading servono a mettere in vendita oggetti e altro. Una guida completa alle funzioni di ciascuna delle API è disponibile nel centro documentazione (http://developer.ebay.com/support/docs/default.aspx). In questo articolo viene descritto principalmente l'utilizzo delle API Finding.

Selezione di una chiamata API In ciascuna API è disponibile una serie di chiamate che potete fare verso le API in questione. Ad esempio, nelle API Finding la chiamata più utile e più comune è findItemsAdvanced, che offre la maggiore flessibilità nel trovare gli oggetti. Le API Finding contengono anche altre chiamate, ad esempio per trovare oggetti in base alla categoria o al nome del Negozio. Una guida completa alle funzioni di ciascuna chiamata è disponibile nel centro documentazione (http://developer.ebay.com/support/docs/default.aspx).

Selezione di un modello Dopo che avete impostato il tipo di chiamata e siete pronti a utilizzarla, potete cambiarne i criteri di ricerca. Si tratta di un modo rapido per aggiungere alcuni campi dei criteri di ricerca di esempio nel campo della richiesta, sulla destra. Potete modificare o rimuovere questi elementi in qualsiasi momento. Se selezionate "Full, generic", avrete a disposizione dei campi vuoti nel riquadro XML Request.  Se selezionate "Partial, pre-filled", vi vengono mostrati alcuni campi di esempio di base già compilati. Questa opzione è utile se non avete molta familiarità con lo strumento e volete abituarvi a usarlo per fare ricerche. Per vedere un esempio che includa i parametri di tracciamento di ePN, selezionate l'opzione "Full, generic": verranno mostrati all'interno dei tag <affiliate>.

Selezione di variazioni di chiamata/campi da includere I contenuti di questo riquadro dipendono dal modello selezionato e costituiscono un modo rapido per aggiungere campi di ricerca al riquadro XML Request. Se il modello è "Full, generic", potete scegliere se aggiungere solo i campi obbligatori oppure tutti i campi possibili. Nel secondo caso, verranno aggiunti tutti i campi possibili al riquadro XML Request sulla destra. Da qui potete esaminarli uno per uno e decidere se utilizzarli o meno. Ad esempio, potreste voler cercare utilizzando parole chiave, ma senza specificare la categoria. Per farlo, utilizzate la riga <keywords>stringa</keywords> e aggiungete le parole chiave che desiderate. Poi eliminate la riga <categoryId>stringa</categoryId>  dal riquadro. Se procedete così per tutti i campi possibili, potete vedere tutte le possibilità e sfruttare al meglio le chiamate API.

Selezione della versione della richiesta di chiamata Come regola generale, non è necessario cambiare questo valore, che si usa solo in circostanze particolari, ad esempio quando sono state apportate modifiche a un'API che hanno causato problemi.

Selezione dell'ID del sito Esistono vari siti eBay per diversi scopi, ad esempio i siti generali nei vari paesi o il sito di eBay Motori negli Stati Uniti. Gli oggetti messi in vendita nel Regno Unito vengono inseriti nel sito britannico, quelli messi in vendita in Germania nel sito tedesco. Aree diverse hanno diversi elenchi di categorie, in base alle esigenze della lingua e di categorizzazione del paese. Potete effettuare una chiamata API solo a un unico sito eBay, che va specificato. Per effettuare una chiamata a più siti dovete creare più chiamate API.

Impostazione dei valori della richiesta

Dopo avere impostato la chiamata API da effettuare potete utilizzare la parte destra della pagina dello strumento per cambiarne i valori della richiesta. Di seguito vengono descritte le funzioni di ciascuna sezione.

Web Service URI (Endpoint) Qui è riportato l'URL Web delle API in uso. Questo campo viene compilato automaticamente in base a quanto impostato nel riquadro "Select an API", ma potete modificarlo manualmente.

HTTP Headers Queste intestazioni vengono compilate automaticamente in base a quello che avete scelto durante l'impostazione della chiamata API, sulla sinistra. Potete modificare questi valori manualmente, ma non è necessario.

XML Request Questo riquadro contiene i dati che verranno inviati alle API e determina che cosa viene restituito. I parametri di ricerca sono contenuti all'interno dei tag XML, ad esempio: <entriesPerPage>2</entriesPerPage>. Prima di effettuare la chiamata, potete modificare i valori tra i tag (in questo caso "2"). Questi esempi precompilati sono utili per capire come utilizzare questa parte dello strumento; per consultare la documentazione completa relativa a ciascun parametro, visitate il centro documentazione (http://developer.ebay.com/support/docs/default.aspx).

Visualizzazione dei risultati

Dopo aver scelto tutti i parametri, inviate l'interrogazione: i risultati verranno mostrati nel riquadro Call Response. La risposta è in formato XML ed è simile a quanto mostrato qui:

Se non ottenete alcun risultato, modificate la chiamata rendendola meno specifica. Se siete soddisfatti della chiamata, potete integrarla nel sito Web (https://developer.ebay.com/quickstartguide/).

Esempio d'uso

Vediamo ora un esempio pratico di come utilizzare lo strumento API per ottenere il seguente obiettivo: vedere un elenco di pantaloncini blu disponibili per acquisto immediato nel Regno Unito.

1. Selezionate l'ambiente "Production", visto che state cercando oggetti in vendita su eBay.

2. Selezionate le API Finding, visto che state cercando oggetti.

3. Utilizzate la chiamata findItemsAdvanced per specificare parametri avanzati per trovare un determinato tipo di oggetto.

4. Scegliete il modello "Full, generic" e includete nella chiamata tutti i campi possibili. Questo vi consente di utilizzare facilmente tutti i parametri necessari e di rimuovere quelli superflui.

5. Impostate l'ID del sito su UK.

6. Scegliete la categoria dei pantaloncini.  La pagina delle categorie di eBay (http://listings.ebay.co.uk/) può aiutarvi a trovare l'ID di categoria che cercate. Anche lo strumento per categorie CGMlab (http://ebay.cgmlab.co.uk/tool-categorytree.php)può fornirvi dettagli sulle categorie disponibili.

7. Impostate i filtri oggetto in modo da includere le inserzioni a prezzo fisso e quelle con formato Compralo Subito e Oggetto del Negozio eBay, i cui oggetti possono essere acquistati immediatamente. Elenco completo dei filtri oggetto per findItemsAdvanced: (http://developer.ebay.com/DevZone/Finding/CallRef/types/ItemFilterType.html).

8. Impostate un filtro di aspetto per trovare solo oggetti il cui colore principale (Main Colour) è blu (Blues). Gli aspetti disponibili all'interno di una categoria possono essere controllati nella pagina delle categorie, in questo caso qui: (http://clothes.shop.ebay.co.uk/Shorts-/15689/i.html?LH_LocatedIn=1&_armrs=1&_dmd=1&_mdo=Clothes-Shoes-Accessories&_mspp=&_pcats=1059%2C11450&_salic=3). Ulteriori documenti sui filtri di aspetto sono disponibili nella documentazione sulle chiamate (http://developer.ebay.com/DevZone/Finding/CallRef/findItemsAdvanced.html#Request.aspectFilter).

9. Specificate i parametri di tracciamento ePN. L'ID di rete di eBay Partner Network è 9; utilizzate il tag trackingId per l'ID campagna.  Il tag <geoTargeting> verrà usato in futuro; impostate il valore su 0.

10. Eliminate eventuali campi non utilizzati in XML Request. Poiché avete scelto di includere tutti i campi possibili, per poter aggiungere facilmente ciò che volete, ci saranno molti campi vuoti inutilizzati. Dovete eliminarli per non condizionare i risultati. La chiamata completa dovrebbe avere un aspetto simile a questo:

11. Dopo avere eseguito la chiamata, vengono restituiti i risultati. Qui sono disponibili tutti i dettagli sulla chiamata e gli oggetti restituiti, compresi i messaggi di errore nel caso di chiamata non riuscita. Qui potete modificare qualsiasi parametro di impostazione della chiamata, inviarla di nuovo e fare vari tentativi per capire come ottenere i risultati migliori.

Opzioni di implementazione

Lo strumento di verifica delle API è un ottimo modo per vedere le chiamate API e usare le varie opzioni per ottenere la chiamata che soddisfa al meglio le vostre esigenze. Sono previste varie opzioni per implementare la chiamata API e vari formati per la chiamata stessa.  Chiamate API Finding di esempio per formato XML e URL standard sono disponibili qui:

http://developer.ebay.com/DevZone/finding/CallRef/findItemsAdvanced.html#Samples

Per informazioni più generali su tutte le opzioni per i formati di richiesta e risposta, consultate questa pagina:

http://developer.ebay.com/DevZone/finding/Concepts/MakingACall.html