Ebay Developer Account.
Nel corso dell'esercitazione utilizzeremo le API di eBay che
richiedono una utenza viluppatore registrata.
Accedere quindi al
portale di registrazione sviluppatori
per ottenere le keys per l'ambiente Sandbox.
Abbiamo visto come fruire dello strumento di ricerca di eBay tramite http e non avremmo difficoltà ad ottenere lo stesso risultato con applicazioni custom, ma una volta ottenuta la pagina HTML di risposta, come la interpretiamo per ottenere i dati che ci interessano?
È chiaro che il formato HTML non è adatto a questo scopo. Per questo eBay espone una serie di Web API per consentire agli sviluppatori l'integrazione delle proprie applicazioni.
Le Web API di Ebay sono divise per categorie d'uso. Quelle che utilizzeremo in questa esercitazione sono:
Finding API : forniscono funzioni di ricerca. Rispondono alla URL http://svcs.sandbox.ebay.com/services/search/FindingService/v1
Shopping API : altra funzioni di ricerca. Rispondono alla URL http://open.api.sandbox.ebay.com/shopping
Trading API : forniscono funzioni per il commercio. Rispondono alla https://api.sandbox.ebay.com/ws/api.dll
Vediamo un esempio d'uso della Finding API con l'operazione
findItemsByKeywords
utilizzando cURL oppure, per una più semplice lettura, un Browser:
curl "http://svcs.sandbox.ebay.com/services/search/FindingService/v1?SECURITY-APPNAME=*****CHANGE-ME******&OPERATION-NAME=findItemsByKeywords&keywords=Android&paginationInput.entriesPerPage=1"
![[Nota]](./stylesheet-images/note.png) |
Nota |
|---|---|
|
|
In risposta otteniamo i risultati della ricerca in formato standard
XML, facilmente interpretabile da un'applicazione. È anche
possibile
avere lo stesso risultato in formato JSON semplicemente appendendo
alla richiesta il parametro
RESPONSE-DATA-FORMAT=JSON
. Per una facile lettura del risultato potete usare
uno dei tanti
visualizzatori JSON online, come
JSON Editor Online
, selezionare
Open URL
ed inserire la URL della richiesta.
Abbiamo visto come fare richieste tramite GET, ma possiamo anche farle tramite POST, fornendo i parametri in formato strutturato.
![[Suggerimento]](./stylesheet-images/tip.png) |
Suggerimento |
|---|---|
Nella documentazione sono indicati i parametri accessori alle richieste . Alcuni di questi sono obbligatori e possono essere indicati sia nella query string, come visto nell'esempio SOAP, sia come header HTTP. Scegliamo di proseguire con gli esempi utilizzando la seconda soluzione per motivi di leggibilità dei comandi. Ricordiamo per aggiungere un header in cURL si utilizza la sintassi -H "NomeHeader: Valore" |
Prendiamo ad esempio la seguante
richiesta XML e salviamola sul file
findItemsByKeywords.request.xml
:
<findItemsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
<keywords>Samsung</keywords>
<paginationInput>
<entriesPerPage>1</entriesPerPage>
</paginationInput>
</findItemsByKeywordsRequest>
ed inviamola tramite
cURL
curl -o findItemsByKeywords.response.xml -H "X-EBAY-SOA-SECURITY-APPNAME: -----CHANGEME-------" -H "X-EBAY-SOA-OPERATION-NAME: findItemsByKeywords" -X POST -T findItemsByKeywords.request.xml http://svcs.sandbox.ebay.com/services/search/FindingService/v1
Proviamo a simulare una vendita ed un acquisto su eBay utilizzando le Web API appena introdotte. Ebay mette a disposizione un ambiente di test chiamato Ebay Sandbox dove possiamo creare utente e simulare compravendite con le applicazioni da noi sviluppate.
|
Nota |
|---|---|
Abbiamo già un account sviluppatore per utilizzare le Shopping API. Per utilizzare le Trading API ci serve un account utente ed il relativo Token. Creiamo quindi una nuova utenza acquirente , accediamo alla pagina di generazione User Token , selezioniamo l'ambiente Sandbox ed il keyset del nostro account sviluppatore (l'unico disponibile). Procediamo nella creazione ed inseriamo, quando richiesto, le credenziali dell'account utente creato in precedenza. Al termine del processo ci viene comunicato il Token da utilizzare. Copiamolo e salviamolo per utilizzarlo per il resto del corso. |
Obiettivo dell'esercitazione. Questa esercitazione si svolge a coppie. Ciascun membro della coppia deve mettere in vendita un oggetto e acquistare quello del compagno. Le interazioni con le Web API devono essere eseguite tramite l'uso del cURL.
STEP 1. Individuare l'identificativo della categoria. L'oggetto che vogliamo mettere in vendita è uno Smartwatch. Dobbiamo quindi trovare l'identificativo della giusta categoria per la messa in vendita. La Shopping API mette a disposizione il metodo GetCategoryInfo per navigare la gerarchia delle categorie. Studiare la documentazione per capire come utilizzarla correttamente. Quella di nostro interesse si trova seguendo il path ROOT > Cell Phones > Smart Watches
|
Suggerimento |
|---|---|
|
La Shopping API prevede un diverso set di parametri obbligatori, come indicato nella documentazione:
ricordando che cambia anche la URL del servizio in http://open.api.sandbox.ebay.com/shopping |
Individuata la categoria di vostro interesse, memorizzatene l'Identificativo per il prossimo step.
STEP 2. Mettere in vendita un nuovo oggetto. Per la messa in vendita di un oggetto, utilizziamo la Trading API ed il partivolare il metodo AddItem .
|
Suggerimento |
|---|---|
|
Come definito nella documentazione, questi gli header richiesti dalla libreria:
ricordando che la URL da invocare è https://api.sandbox.ebay.com/ws/api.dll che, essendo in https richiede in cURL di aggiungere l'opzione -k per trustare il certificato server (argomento si sicurezza trattato nelle future lezioni). |
Dalla documentazione potete verificare che i dettagli per l'inserimento di una nuova richiesta sono numerosi, ma molti opzionali. Per aiutarvi nell'impresa di costruirne una valida, vi viene fornito di seguito un template di richiesta con i soli campi obbligatori, nel quale dovrete inserire l' IdCategoria trovato in precedenza, un ID univoco per questa richiesta (un MD5, stringa di 32 caratteri esadecimali) ed il vostro eBayAuthToken :
<?xml version="1.0" encoding="utf-8"?> <AddItemRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <Item> <Title>Smartwatch Clementoni</Title> <Description>Lo Smartwatch dei tuoi sogni!</Description> <PrimaryCategory> <CategoryID>---ID CATEGORIA TROVATO ALLO STEP 1 ---</CategoryID> </PrimaryCategory> <StartPrice>1.00</StartPrice> <ConditionID>3000</ConditionID> <CategoryMappingAllowed>true</CategoryMappingAllowed> <Country>US</Country> <Currency>USD</Currency> <DispatchTimeMax>3</DispatchTimeMax> <ListingDuration>Days_7</ListingDuration> <PaymentMethods>PayPal</PaymentMethods> <PayPalEmailAddress>magicalbookseller@yahoo.com</PayPalEmailAddress> <PostalCode>95125</PostalCode> <Quantity>1</Quantity> <ReturnPolicy> <ReturnsAcceptedOption>ReturnsAccepted</ReturnsAcceptedOption> <RefundOption>MoneyBack</RefundOption> <ReturnsWithinOption>Days_30</ReturnsWithinOption> <Description> Condizioni ottime! </Description> <ShippingCostPaidByOption>Buyer</ShippingCostPaidByOption> </ReturnPolicy> <ShippingDetails> <ShippingType>Flat</ShippingType> <ShippingServiceOptions> <ShippingServicePriority>1</ShippingServicePriority> <ShippingService>USPSMedia</ShippingService> <ShippingServiceCost>2.50</ShippingServiceCost> </ShippingServiceOptions> </ShippingDetails> <Site>US</Site> <UUID>-----32 CARATTERI TRA CIFRE E LETTERE DA A AD F----</UUID> </Item> <RequesterCredentials> <eBayAuthToken>---- Lo User Token acquisito in precedenza ----</eBayAuthToken> </RequesterCredentials> <WarningLevel>High</WarningLevel> </AddItemRequest>
Se la pubblicazione dell'articolo si completa con successo, dalla risposta recuperate l'identificativo dell'Item creato e comunicarlo al compagno d'esercitazione per procedere allo Step 3.
STEP 3. Fare un'offerta. Utilizziamo sempre la Trading API per fare un'offerta per l'asta creata dal vostro compagno con il metodo PlaceOffer . Completiamo quindi la richiesta che segue con l'identificativo dell'oggetto creato dal nostro compagno:
<?xml version="1.0" encoding="utf-8"?> <PlaceOfferRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <ItemID>---ID ITEM DEL COMPAGNO ---</ItemID> <Offer> <Action>Bid</Action> <MaxBid>20.00</MaxBid> <Quantity>1</Quantity> </Offer> <EndUserIP>10.0.0.1</EndUserIP> <RequesterCredentials> <eBayAuthToken>---- Lo User Token acquisito in precedenza ----</eBayAuthToken> </RequesterCredentials> </PlaceOfferRequest>
Se l'acquisto si completa con successo, recuperare dalla risposta l'identificativo dell'Item creato e comunicarlo al compagno d'esercitazione.
