martedì 11 agosto 2009

Integrare le funzionalità di Bing nei nostri siti web – Parte 5 – JSON & SOAP

In questo post della serie riservata a Bing diamo, rapidamente, un’occhiata agli entry point delle API che si basano sui protocolli JSON e SOAP. Le precedenti puntate sono disponibili ai seguenti link: Parte 1, Parte 2, Parte 3 e Parte 4.

     JSON

L’entry point per ottenere una risposta alla nostra ricerca con la serializzazione JSON è il seguente:

http://api.search.live.net/json.aspx

Tutti i discorsi visti nei precedenti posts relativi ai parametri di configurazione della ricerca sono ancora validi, per questo motivo, se effettuiamo una richiesta Get al seguente indirizzo:

http://api.search.live.net/json.aspx?Appid=<appid>&query=Bing&sources=Web&Ewb.count=2

otteniamo:

captured_Image.png

     Parametro JsonType

Nelle richieste JSON è possibile specificare il formato con cui restituire i risultati della ricerca tramite il parametro JsonType.
I possibili valori per JsonType sono:

raw : i risultati di ricerca sono restituiti in puro JSON;

callback : i risultati di ricerca vengono restituiti come argomento della funzione javascript indicata nel parametro JsonCallback;

function : viene restituita una funzione Javascript la cui chiamata restituisce i risultati di ricerca.

Se il parametro non viene assegnato, viene preso il valore raw per default.

     SOAP

Le funzionalità di ricerca di Bing sono utilizzabili anche tramite il protocollo SOAP referenziando il wsdl presente all’indirizzo:

http://api.bing.net/search.wsdl?AppID=<appid>&Version=2.2

Nella seguente figura riportiamo uno scorcio del wsdl:

captured_Image.png[6]

Per informazioni sull’utilizzo dei servizi web service esposti in formato SOAP e delle classi proxy che vengono generate dalla reference al WSDL, vi consiglio di guardare la documentazione ufficiale al seguente link.

La seguente funzione permette di effettuare la ricerca dei video presenti in rete che rispondono ai criteri di ricerca passati per argomento:

Public Function Search(ByVal text As String, _



                       ByVal recordCount As UInteger, _



                       ByRef totalPage As UInteger, _



                       Optional ByVal pageNumber As UInteger = 0, _



                       Optional ByVal market As String = "it-IT") As List(Of BingAPI.VideoResult)



        Dim retList As List(Of BingAPI.VideoResult) = Nothing



        If Not String.IsNullOrEmpty(text) Then



            Dim startIndex = recordCount * pageNumber



            Dim parameters = New BingAPI.SearchRequest()



            parameters.Video = New BingAPI.VideoRequest()



            parameters.Video.Count = recordCount



            parameters.Video.Offset = startIndex



            parameters.Market = market



            parameters.Query = text



            Using srv As New BingAPI.BingPortTypeClient()



                Try



                    Dim response = Me._Service.Search(parameters)



                    retList = response.Video.Results.ToList()



                    totalPage = CUInt(Math.Truncate(response.Video.Total / recordCount + 0.5))



                Catch ex As Exception



                    Throw



                End Try



            End Using



        Else



            retList = New List(Of BingAPI.VideoResult)



        End If



        Return retList



    End Function




La funzione accetta un testo di ricerca, un numero di record per pagina, il numero di pagina da restituire (opzionale), il market (opzionale) e restituisce il numero totale (approssimato) di elementi della ricerca e la lista dei risultati.

La classe VideoResult è una delle classi wrapper generate dalla reference al servizio SOAP di Bing:



captured_Image.png[1]



La classe BingPointPortClient è, invece, la classe per l’accesso al servizio di ricerca:



 



captured_Image.png[1]



Il protocollo SOAP è, decisamente, più semplice da utilizzare, fornendo in maniera automatica le wrapper classi per la gestione dei risultati.



     Riferimenti



Per maggiori informazioni potete consultare la documentazione presente ai seguenti link:



Bing API, Version 2


Bing Developer Center



 



lunedì 10 agosto 2009

Integrare le funzionalità di Bing nei nostri siti web – Parte 4 – Gestione degli errori

Dopo aver dato un’occhiata alle basi delle API di Bing e di come possiamo utilizzarle (post1, post2 e post3) , in questo post ci occuperemo di come gestire  eventuali errori.

Supponiamo di eseguire la seguente richiesta Get:

http://api.search.live.net/xml.aspx?Appid=<appid>&query=&sources=images

dove <appid> è il nostro AppID descritto nei precedenti post.

Il risultato che otteniamo è il seguente:

captured_Image.png

Eventuali errori nella richiesta sono contenuti nella collezione di nodi <Errors> il cui singolo figlio ha il seguente formato:

captured_Image.png[6]

Tra i child del nodo <Error> troviamo:

<Code> : codice del messaggio d’errore (vedere tabella seguente);
<Message> : messaggio d’errore;
<Parameter> : eventuale parametro che ha generato l’errore;
<Value> : valore del parametro errato;
<HelpUrl> : URL della pagina MSDN di aiuto.

L’errore si verifica, generalmente, se l’URL della richiesta non è corretto oppure se la piattaforma Bing ha dei problemi oppure se l’appid utilizzato non è valido.
Non vengono restituiti errori, invece, se la ricerca non ha trovato risultati. In questo caso si hanno le collezioni dei risultati vuote.

Nella seguente tabella sono riportati i possibili errori (nell’attuale versione delle API)   che si possono verificare:

Codice

Descrizione

1001

Nei parametri della query non è presente un parametro obbligatorio. In questo caso, il nodo <Parameter> fornisce indicazioni su quale parametro manca e non è presente il nodo <Value>.

1002

Un parametro ha un valore errato. Il nodo <Parameter> fornisce indicazioni sul nome del parametro mentre il nodo <Value> riporta il valore errato.

1005

La query è troppo lunga. La query non può superare i 2048 bytes.

2001

L’appid che si sta utilizzando potrebbe essere disabilitato. Se l’appid è errato, si ottiene un errore con codice 1002.

2002

L’appid ha superato il massimo numero di bytes scaricabili. Per maggiori informazioni si può consultare i termini di utilizzo del servizio.

2003

L’appid che si sta utilizzando, pur essendo valido, non ha accesso alla sorgente di ricerca richiesta. Può succedere che alcune sorgenti di ricerca siano disponibili solo per particolari contratti con Microsoft.

3001

Una o più delle sorgenti di ricerca richieste non sono attualmente disponibili.

3002

Le API di Bing sono momentaneamente non disponibili.

4001

Per comprendere il tipo di errore è necessario

     Riferimenti

Per maggiori informazioni potete consultare la documentazione presente ai seguenti link:

Bing API, Version 2
Bing Developer Center

 

domenica 9 agosto 2009

Integrare le funzionalità di Bing nei nostri siti web – Parte 3 – Strutture Dati

In questo post analizzeremo in dettaglio le strutture dati XML relative ad alcune delle più interessanti sorgenti di ricerca viste nei precedenti posts (parte 1 e parte 2). Ci occuperemo dei servizi offerti dall’entry point XML poiché più semplice e di immediato utilizzo tramite un browser e perché gli altri due entry point (JSON e SOAP) sono abbastanza simili

     Web

LA sorgente Web consente di eseguire ricerche sulle risorse web presenti in rete.

Eseguiamo la seguente richiesta Get:

http://api.search.live.net/xml.aspx?Appid=<appid>&query=Bing&sources=Web

dove <appid> è il nostro AppID descritto nei precedenti post.

Il risultato che otteniamo è il seguente:

04-08-2009 9.14

L’elenco dei risultati della ricerca è composto da nodi <web:WebResult> con il seguente formato:

04-08-2009 9.19

Tra i child del nodo <web:WebResult> troviamo:

<web:Title> : titolo del risultato;
<web:Description> : descrizione del risultato;
<web:Url> : indirizzo completo del risultato;
<web:CacheUrl> : indirizzo della copia del risultato contenuta nella cache di Bing;
<web:DisplayUrl> : indirizzo da visualizzare all’utente;
<web:DateTime> : data di ultimo aggiornamento.

 

     Image

La sorgente Image consente di effettuare ricerche su risorse immagini presenti in rete.

Eseguiamo la seguente richiesta Get:

http://api.search.live.net/xml.aspx?Appid=<appid>&query=Bing&sources=Image

Il risultato che otteniamo è il seguente:

captured_Image.png

L’elenco dei risultati della ricerca è composto da elementi <mms:ImageResult> con il seguente formato:

captured_Image.png[4]

Tra i nodi figlio troviamo:

<mms:Title> : Titolo del risultato;
<mms:MediaUrl> : URL a cui si trova l’immagine;
<mms:Url> : URL della pagina che contiene l’immagine;
<mms:DisplayUrl> : URL della pagina contenente l’immagine da visualizzare all’utente;
<mms:Width> : larghezza dell’immagine;
<mms:Height> : altezza dell’immagine;
<mms:FileSize> : dimensione del file di immagine;
<mms:ContentType> : tipo di immagine (ad esempio image/jpeg) ;
<mms:Thumbnail> : dati relativi alla miniatura dell’immagine (si tratta di un elemento con nodi figli).

 

     Video

La sorgente di ricerca Video permette di effettuare ricerche sui file di tipo video presenti in rete.

Eseguiamo la seguente richiesta Get:

http://api.search.live.net/xml.aspx?Appid=<appid>&query=Bing&sources=Video

Il risultato che otteniamo è il seguente:

captured_Image.png[6]

L’elenco dei risultati della ricerca è composto da elementi <mms:VideoResult> con il seguente formato:

captured_Image.png[8]

Tra i nodi figli troviamo:

<mms:Title> : titolo del video;
<mms:PlayUrl> : URL del video originale;
<mms:SourceTitle> : nome della sorgente del video;
<mms:RunTime> : se disponibile, indica la durata in millisecondi;
<mms:ClickThroughPageUrl> : URL del filmato attraverso la video page di Bing (una sorta di cache);
<mms:StaticThumbnail> : informazioni circa l’immagine da utilizzare come miniatura.

 

     News

La sorgente di ricerca News consente di effettuare ricerche sulle notizie presenti in rete.

Eseguiamo la seguente richiesta Get:

http://api.search.live.net/xml.aspx?Appid=<appid>&query=Bing&sources=News

Il risultato che otteniamo è il seguente:

captured_Image.png[10]

L’elenco dei risultati della ricerca è composto da elementi <news:NewsResult> con il seguente formato:

 captured_Image.png[12]

Tra i nodi figli troviamo:

<news:Title> : Titolo della notizia;
<news:Url> : URL della notizia;
<news:Source> : Nome della sorgente della notizia;
<news:Snippet> : Breve descrizione della notizia;
<news:Date> : Data in cui il contenuto è stato indicizzato;
<news:BreakingNews> : Indica se si tratta di un “ultima notizia” o meno.

     Translation

La sorgente di ricerca Translation permette di tradurre vocaboli da una lingua ad un’altra.

Eseguiamo la seguente richiesta Get:

http://api.search.live.net/xml.aspx?Appid=<appid>&query=mamma&sources=Translation&Translation.TargetLanguage=en&Translation.SourceLanguage=it

Il risultato che otteniamo è il seguente:

captured_Image.png[1]

L’elenco dei risultati della ricerca è composto da elementi <tra:TranslationResult> al cui interno troviamo il nodo <tra:TranslatedTerm> che riporta la traduzione del vocabolo presente nel parametro query.

     Riferimenti

Per maggiori informazioni potete consultare la documentazione presente ai seguenti link:

Bing API, Version 2
Bing Developer Center

 

sabato 8 agosto 2009

Integrare le funzionalità di Bing nei nostri siti web – Parte 2 – Parametri di Query

In questo post ha lo scopo di esporre i possibili parametri che si possono utilizzare nei servizi offerti dalla piattaforma Bing (esposta nel precedente post).

Anche in questo caso utilizzeremo la modalità di accesso XML. Il discorso si può facilmente ripetere per le altre modalità JSON e SOAP.

Non esaminerò tutte le possibili sorgenti di ricerca fornite da Bing ma solamente quelle ritenute più interessanti, fornendo comunque gli opportuni riferimenti per potersi documentare sulle sorgenti non citate.

Per riprendere il discorso, una chiamata alle API di Bing per recuperare dei risultati di ricerca ha la forma:

 http://api.search.live.net/xml.aspx?Appid=<appid>&query=<parole da cercare>&sources=<sorgenti di ricerca> 

     Parametri comuni

Esistono dei parametri generali, comuni, cioè, a qualsiasi eventuale fonte di ricerca si scelga.
In particolare abbiamo:

AppId : AppID generato sul sito riservato ai Developer, necessario per accedere ai servizi;

Query : elenco delle parole da ricercare;

Sources : una o più sorgenti dati (vedere post precedente);

Version : rappresenta la versione della API di Bing che si intende utilizzare. Se non impostato viene preso il valore 2.1;

Market : rappresenta la nazione/cultura per cui deve essere effettuata la ricerca. Se non viene impostato, il motore di Bing cerca di dedurre la lingua tramite algoritmi quali l’indirizzo IP e così via;

Adult : indica il filtro per adulti impostato per la ricerca. Se non impostato, viene preso il valore di default, dipendente dal market selezionato. I possibili valori del parametro sono:
    
Off : non viene utilizzato alcun filtro,
    
Moderate : i risultati della ricerca non includono immagini o
                      video ma possono includere del testo a sfondo
                      sessuale,
     Strict : i risultati non debbono includere nè testo, nè
                immagini e nè foto per adulti;

Options : permette di impostare alcune proprietà comuni a tutte le sorgenti di ricerca come l’abilitazione del riconoscimento automatico della nazione;

Latitude : imposta la latitudine geografica in cui centrare la ricerca in modo da rendere la ricerca più accurata;

Longitude : imposta la longitudine geografica in cui centrare la ricerca in modo da renderla più accurata;

UILanguage : imposta la lingua dell’interfaccia grafica;

Radius : imposta il raggio di ricerca per la richiesta. Da utilizzare alla stregua della latitudine e della longitudine per rendere più accurata la ricerca.

     Parametri comuni a tutte le sorgenti

Esistono, inoltre, altri parametri comuni a tutte le sorgenti di ricerca e che possono essere valorizzati in maniera indipendente da sorgente a sorgente.
Questi parametri si possono impostare sulla singola sorgente di ricerca utilizzando la sintassi:

<nome sorgente>.<parametro>

Tra questi troviamo:

Count : specifica il numero di record da restituire;

Offset : specifica il numero del primo record dei risultati di ricerca.

Di seguito riporto i parametri di due sorgenti interessanti come Image e Video (per le altre sorgenti si possono consultare i riferimenti riportati in calce al post).

     Image

La sorgente Image permette di ricercare immagini.
Possiamo decidere quale tipologia di immagini ricercare in termini di dimensioni (altezza e larghezza), presenza o meno di volti o persone, formato dell’immagine (ritratto o paesaggio), se si tratta di un disegno o una foto oppure se è a colori o meno.
Il parametro è Image.Filters e può assumere la combinazione di una serie di valori (l’insieme dei valori è consultabile al seguente link).

Ad esempio, la seguente richiesta:

http://api.search.live.net/xml.aspx?Appid=<appid>&query=colosseo&sources=Image&Image.Filters=Size:Small+Color:Monochrome

restituisce il seguente risultato:

04-08-2009 22.45

La prima immagine risultato è :

pianta1_small

     Video

La sorgente di tipo Video consente di ricercare tra i file di tipo video presenti in rete.

Se proviamo a digitare il seguente URL

http://api.search.live.net/xml.aspx?Appid=<appid>&query=Visual+Studio+2010&sources=Video&market=it-IT&Video.Filters=Resolution:Low

nella barra indirizzi del browser, otteniamo la seguente risposta: 

captured_Image.png[7]

     Riferimenti

Per maggiori informazioni potete consultare la documentazione presente ai seguenti link:

Bing API, Version 2
Bing Developer Center

 

martedì 4 agosto 2009

Integrare le funzionalità di Bing nei nostri siti web – Parte 1 - Introduzione

Vorrei inaugurare una serie di post illustrarvi le API di base dei servizi messi a disposizione dal motore di ricerca Bing.

Bing è accessibile attraverso tre differenti protocolli: XML, JSON e SOAP.
Queste tre modalità di accesso ai risultati ci permettono di scegliere il miglior modo per integrare funzionalità di ricerca nella nostra applicazione.

Grazie al protocollo XML, possiamo fare esperimenti sulle API di Bing utilizzando un normale browser.
Per fare questo è necessario recuperare un AppID, un parametro da passare alla richiesta Get che faremo con il browser che permette al sistema di riconoscerci.
Possiamo generare l’AppID andando sul sito per lo sviluppo con Bing (http://search.live.com/developers), loggarci con il nostro Windows Live ID e creare l’AppID utilizzando l’apposito link.
Per la creazione dell’AppID sarà necessario inserire alcune informazioni relative all’applicazione che utilizzerà l’ID generato:

 04-08-2009 8.03

Una volta che abbiamo in mano l’AppID possiamo sperimentare le funzionalità utilizzando un normale browser e una semplice richiesta Get con opportuni parametri in query string.
Gli url che possiamo utilizzare per effettuare dei test sono i seguenti:

http://api.search.live.net/xml.aspx (risultati in XML)

http://api.search.live.net/json.aspx (risultati in JSON)

Per semplicità utilizziamo il primo dei due (ma ciò che diremo vale anche per il secondo).
La richiesta Get va corredata da alcuni parametri in query string (oltre al già citato AppID):

Query : il parametro contiene le parole da ricercare (ad esempio “Bing”);
Sources : indica la sorgente da cui attingere i risultati. I possibili valori per questo parametro sono:

  • Ad : ricerca di inserzioni pubblicitarie;
  • Image  : immagini;
  • InstantAnswer : risposte a domande quali “quanti secondi ci sono in un anno?”, etc., etc.;
  • MobileWeb : contenuti web per dispositivi mobile;
  • News : notizie ;
  • Phonebook : dettagli su attività commerciali;
  • RelatedSearch : contenuti legati alla ricerca effettuata e di possibile interesse;
  • Spell : risultati con uno spelling simile a quello ricercato;
  • Translation : traduzioni tra differenti lingue;
  • Video : video correlati alla ricerca effettuata;
  • Web : classici contenuti web.

e sono valide anche  combinazioni degli stessi, utilizzando il carattere “+”.

La scelta oculata della sorgente dati ci consente di fornire differenti tipologie di risultati per ogni ricerca effettuata dall’utente.

Esistono altri parametri utilizzabili che gestiscono al paginazione dei risultati e che vedremo più avanti.

Tanto per entrare nel vivo, proviamo ad aprire il browser e a digitare il seguente URL:

http://api.search.live.net/xml.aspx?Appid=<appid>&query=Bing&sources=Web

dove <appid> va sostituito con il proprio AppID visto in precedenza.
Il risultato che otteniamo è il seguente:

04-08-2009 7.20

L’Header contiene le parole utilizzate per la ricerca, mentre il Body contiene gli effettivi risultati.

In caso di sorgenti multiple, ad esempio “Web+News+Image”, otteniamo:

04-08-2009 8.14

Per ogni tipologia di sorgente richiesta vengono forniti (con un particolare namespace) il numero totale dei risultati, l’offset (in sostanza la pagina di visualizzazione come vedremo avanti) e l’elenco dei primi n elementi trovati (con n=10 per impostazione predefinita).

Il nodo Total (tipizzato nelle diverse tipologie di sorgenti) rappresenta il numero totale (stimato) dei valori che soddisfano i parametri di ricerca. Questo valore va preso con le pinze in quanto potrebbe non essere esattamente uguale al numero dei risultati effettivi. Si tratta di una stima e come tale va utilizzata.

Il nodo Offset ci dice quale è l’indice del primo nodo risultato riportato nella lista dei risultati. Ci fornisce indicazioni riguardo alla pagina di risultati che stiamo esaminando.

Possiamo variare il numero di elementi di ogni sorgente restituiti per ogni ricerca utilizzando il parametro <sourcetype>.count. In questo modo, se aggiungiamo il parametro web.count=20 alla nostra query, otterremo 20 elementi di ricerca per il web e 10 per tutte le altre eventuali sorgenti richieste.
Facendo dei tentativi empirici si può riscontrare che se mettiamo, ad esempio, Web.count=51 otteniamo un errore che, invece, non otteniamo con Web.count=50.

Per poter lavorare sull’offset dei risultati (ottenendo, quindi le pagine successive dei risultati di ricerca) possiamo agire sul parametro <sourceType>.offset. In questo modo, se mettiamo Web.offset=21 ed eseguiamo la query, otteniamo i risultati a partire dal 21-esimo.

Ovviamente, i parametri visti in precedenza possono lavorare i combinazione per fornirci ampia flessibilità nelle ricerche.

Nel prossimo post analizzeremo i possibili parametri che possono essere utilizzati nelle API di Bing.

     Riferimenti

Per maggiori informazioni potete consultare la documentazione presente ai seguenti link:

Bing API, Version 2
Bing Developer Center

 

lunedì 3 agosto 2009

Anche Trenitalia ha dimenticato l’italiano?

Oggi, in viaggio, sono andato sulla home page del sito Trenitalia:

image

e ho notato che l’offerta estate per le famiglie si chiama “Offerta Familia Estate”.

image

Sono io che erro oppure il termine “Familia“ non è propriamente italiano?  Magari è un termine aulico? Boh!!!

Technorati Tag: ,