Používáme Live Search API

S Live Search API můžete pracovat z jakéhokoliv programovacího jazyka. U výstupního formátu si můžete vybrat mezi JSON a XML. Ukážeme, jak s rozhraním pracovat pomocí C#, Visual Basicu, PHP a v Silverlight 2.0 aplikaci. Zaměříme se na novou, rozšířenou, verzi rozhraní.

Před pár lety vyšel na Root.cz článek o využití Live Search API, na který zde částečně navážeme. Původní API, popisované ve zmiňovaném článku, využívalo klasické webové služby, které nejsou úplně jednoduché na použití.

Poslední verze Live Search API byla proto rozšířena o rozhraní, které vychází z RESTFul Web Services. V podstatě stačí sestavit URL a jako odpověď dostanete buď výsledek hledání ve formátu XML nebo ve formátu JSON. V článku si ukážeme, jak pracovat s Live Search API pomocí PHP a také si ukážeme, jak lze využít webovou službu tohoto typu v Silverlight 2.0 aplikaci.

Abyste mohli začít používat Live Search API, musíte mít tzv. App ID. Je to unikátní kód, který bude při každém volání služby posílat vaše aplikace a vytvoříte si ho na příslušné stránce. V článku se budeme věnovat rozhraní REST a nebudeme si popisovat rozhraní SOAP. Dotaz na službu vypadá následovně:

http://api.search.live.net/{0}.aspx?AppId={1}&Market={2}&Query={3}&Sources={4} 

{0} – formát odpovědi. Může nabývat hodnot json nebo xml.
{1} – Vaše App ID.
{2} – Lokalizace a národní nastavení, pro češtinu to je cs-CZ.
{3} – Hledaný text. Pokud funkce, kterou používáte pro URL encoding, používá pro mezeru znak +, je ho třeba změnit na %20.
{4} – Zdroje hledání, typicky web nebo image. Více na Working with SourceTypes. Pokud chcete prohledávat více zdrojů najednou, vkládejte mezi ně znak +. Hledání na webu a v obrázcích pak vypadá  Sources=web+image.

Další parametry vychází z vlastností objektu SearchRequest.

Každý zdroj hledání, který byl uveden v dotazu, má ve výsledku vlastní sekci. Na dotaz:

http://api.search.live.net/json.aspx?AppId={1}&Market=en-US&Query=dog&Sources=web+image&Web.Count=1&Image.Count=1 

Dostanete odpověď:

{"SearchResponse":
    {
        "Version":"2.0",
        "Query":
        {
            "SearchTerms":"dog"
        },
        "Web":
        {
            "Total":195000000,
            "Offset":0,
            "Results":[
            {
                "Title":"Dog - Wikipedia, the free encyclopedia",
                "Description":"The dog (Canis lupus familiaris) [2] is a domesticated subspecies of the gray wolf, a mammal of the Canidae family of the order Carnivora. The term encompasses both feral and pet ... ",
                "Url":"http://en.wikipedia.org/wiki/Dog",
                "DisplayUrl":"http://en.wikipedia.org/wiki/Dog",
                "DateTime":"2008-12-17T16:17:47Z"
            }]
        },
        "Image":
        {
            "Total":32500000,
            "Offset":0,
            "Results":[
            {
                "Title":"Global Action Network: Animals: Dogs",
                "MediaUrl":"http://www.gan.ca/images/hooks/dog.bmp",
                "Url":"http://www.gan.ca/animals/dogs.en.html",
                "DisplayUrl":"http://www.gan.ca/animals/dogs.en.html",
                "Width":390,
                "Height":358,
                "FileSize":419630,
                "Thumbnail":
                {
                    "Url":"http://ts1.images.live.com/images/thumbnail.aspx?q=519708870276&id=5ebf8483db6abf379607b2676ec3e08b",
                    "ContentType":"image/jpeg",
                    "Width":160,
                    "Height":146,
                    "FileSize":5297
                }
            }]
        }
    }
} 

Pokud v dotazu zaměníte json.aspx za xml.aspx, bude výsledek následující:

<?xml version="1.0" encoding="utf-8" ?>
<?pageview_candidate?>
<SearchResponse xmlns="http://schemas.microsoft.com/LiveSearch/2008/04/XML/element" Version="2.0">
  <Query>
    <SearchTerms>dog</SearchTerms>
  </Query>
  <web:Web xmlns:web="http://schemas.microsoft.com/LiveSearch/2008/04/XML/web">
    <web:Total>195000000</web:Total>
    <web:Offset>0</web:Offset>
    <web:Results>
      <web:WebResult>
        <web:Title>Dog - Wikipedia, the free encyclopedia</web:Title>
        <web:Description>The dog (Canis lupus familiaris) [2] is a domesticated subspecies of the gray wolf, a mammal of the Canidae family of the order Carnivora. The term encompasses both feral and pet ... </web:Description>
        <web:Url>http://en.wikipedia.org/wiki/Dog</web:Url>
        <web:DisplayUrl>http://en.wikipedia.org/wiki/Dog</web:DisplayUrl>
        <web:DateTime>2008-12-17T16:17:47Z</web:DateTime>
      </web:WebResult>
    </web:Results>
  </web:Web>
  <mms:Image xmlns:mms="http://schemas.microsoft.com/LiveSearch/2008/04/XML/multimedia">
    <mms:Total>32500000</mms:Total>
    <mms:Offset>0</mms:Offset>
    <mms:Results>
      <mms:ImageResult>
        <mms:Title>Global Action Network: Animals: Dogs</mms:Title>
        <mms:MediaUrl>http://www.gan.ca/images/hooks/dog.bmp</mms:MediaUrl>
        <mms:Url>http://www.gan.ca/animals/dogs.en.html</mms:Url>
        <mms:DisplayUrl>http://www.gan.ca/animals/dogs.en.html</mms:DisplayUrl>
        <mms:Width>390</mms:Width>
        <mms:Height>358</mms:Height>
        <mms:FileSize>419630</mms:FileSize>
        <mms:Thumbnail>
          <mms:Url>http://ts1.images.live.com/images/thumbnail.aspx?q=519708870276&id=5ebf8483db6abf379607b2676ec3e08b</mms:Url>
          <mms:ContentType>image/jpeg</mms:ContentType>
          <mms:Width>160</mms:Width>
          <mms:Height>146</mms:Height>
          <mms:FileSize>5297</mms:FileSize>
        </mms:Thumbnail>
      </mms:ImageResult>
    </mms:Results>
  </mms:Image>
</SearchResponse> 

Zpracování odpovědi ve formátu JSON je asi zřejmé, stačí použít některý z parserů pro tento formát, ti odvážnější mohou použít javascriptovou funkci  eval.

ČTĚTE K TÉMATU: Seriál JSON pro výměnu dat na webu

U odpovědi ve formátu XML je třeba věnovat pozornost práci se jmennými prostory. Všimněte si, že některé elementy, jako například SearchResponse, nemají prefix jmenného prostoru, ale přesto do jmenného prostoru, konkrétně http://schemas­.microsoft.com/Li­veSearch/2008/04/X­ML/element, patří. Pokud používáte parser XML, který vyžaduje registraci jmenných prostorů, nesmíte na tento jmenný prostor zapomenout.

Hledání na straně webového serveru pomocí ASP.NET a PHP

Při použití formátu XML pro výsledek hledání se přímo nabízí použít XSLT transformace. V ASP.NET můžeme použít serverový ovládací prvek asp:Xml nebo objekt XslCompiledTran­sform. V případě použití serverového ovládacího prvku asp:Xml stačí jen nastavit umístění XSLT šablony pro transformaci a pak načíst odpověď ze serveru. O vlastní transformaci a vykreslení výsledku se už postará ovládací prvek.

…
<asp:Xml ID="xmlTransformace" TransformSource="xslt/web.xslt" runat="server"></asp:Xml>
…
 
…
string url = String.Format(SEARCH_URL,
APP_ID,
"cs-CZ",
Uri.EscapeDataString(txtSearch.Text));
 
WebRequest request = WebRequest.Create(new Uri(url));
WebResponse response = request.GetResponse();
StreamReader data = new StreamReader(response.GetResponseStream());
 
xmlTransformace.DocumentContent = data.ReadToEnd();
… 

Pokud používáte PHP, je postup velmi podobný.

…
$searchTerm = str_replace('+', '%20', urlencode($_POST['txtSearch']));
$searchUrl = "http://api.search.live.net/xml.aspx?AppId=$APPID&Market=cs-CZ&Query=$searchTerm&Sources=web";
 
$xsl = new DOMDocument();
$xsl->load('xslt/web.xslt');
 
$xslt = new XSLTProcessor();                                        
$xslt->importStylesheet($xsl);
 
$xml = new DOMDocument();
$xml->load($searchUrl);
 
echo '<div>' . $xslt->transformToXML($xml) . '</div>';
… 

Silverlight 2.0 aplikace jako klient pro Live Search

Jedna z vlastností Silverlightu 2.0 je bezproblémová komunikace napříč doménami a snadné zpracování XML pomocí LINQ. Pokud chcete v Silverlight 2.0 aplikaci využívat služeb třetích stran, které poskytují data ve formátu XML, musíte myslet na dvě věci:

  1. Veškerá komunikace se serverem probíhá v Silverlightu 2.0 asynchronně.
  2. Silverlight 2.0 nepodporuje XPath, tím pádem ani XSLT.
…
private void btnSearch_Click(object sender, RoutedEventArgs e)
{
    string url = String.Format(SEARCH_URL,
                                APP_ID,
                                "cs-CZ",
                                Uri.EscapeDataString( txtSearch.Text));

    WebRequest request = WebRequest.Create(new Uri(url));

    // Asynchronni spusteni operace, jako parametr se predava pozadavek
    // ktery bude obsahovat odpoved ze server
    request.BeginGetResponse(OnData, request);
}

private void OnData(IAsyncResult e)
{
    // ziskani pozadavku na server
    WebRequest request = (WebRequest)e.AsyncState;
    // ukonceni asynchronniho volani
    WebResponse response = (WebResponse)request.EndGetResponse(e);

    StreamReader data = new StreamReader(response.GetResponseStream());

    XDocument d = XDocument.Parse(data.ReadToEnd());

    // prevedeni XML do objektu pomoci LINQ,
    // nezapomente registrovat prislusne jmenne prostory
    var images = from i in d.Descendants(mms + "ImageResult")
                 select new Image
                 {
                     Url = i.Element(mms + "Thumbnail").Element(mms + "Url").Value,
                     Title = i.Element(mms + "Title").Value
                 };


    // Synchronizace s UI
    Dispatcher.BeginInvoke(() => { lstData.ItemsSource = images; });
}
… 

Příznivci jazyka Visual Basic mohou pro zpracování XML využít XML literály. Opět musíte registrovat jmenné prostory.

…
Dim images As List(Of Image) = (From i In d...<mms:ImageResult> _
         Select New Image() _
                With _
                { _
                    .Url = i.<mms:Thumbnail>.<mms:Url>.Value, _
                    .Title = i.<mms:Title>.Value _
                }).ToList()
… 

Live Search API a Microsoft Word 2007

Microsoft Word 2007

Službu Live Search můžete samozřejmě využít i v klasických „exe“ aplikacích, ale i v trochu méně tradiční funkci. Následující kód je část doplňku pro Microsoft Word 2007, který označený text v dokumentu hledá na Wikipedii, a pokud heslo najde, tak text převede na hyperlink odkazující na heslo v encyklopedii.

Pokud si chcete vyzkoušet tuto ukázku, budete kromě Microsoft Office 2007 (stačí Home & Student) potřebovat také Visual Studio 2008 SP1 Professional, které můžete jako studenti získat zdarma v rámci projektu Dreamspark.

private void cmdSearch_Click(object sender, RibbonControlEventArgs e)
{
    Word.Selection selectedText = Globals.ThisAddIn.Application.Selection;
 
    string query = String.Format("{0} site:{1}.wikipedia.org",
                                Uri.EscapeDataString(selectedText.Text.Trim()),
                                cmbWeb.Text.ToLower());
 
 
    string url = String.Format(SEARCH_URL,
                                APP_ID,
                                "cs-CZ",
                                query);
 
    WebRequest request = WebRequest.Create(new Uri(url));
    WebResponse response = request.GetResponse();
    StreamReader data = new StreamReader(response.GetResponseStream());
 
    XDocument d = XDocument.Parse(data.ReadToEnd());

    XElement resultElement = d.Descendants(web + "WebResult").FirstOrDefault<XElement>();
 
    if (resultElement == null)
    {
        return;
    }

    object missing = System.Reflection.Missing.Value;

    object resultUrl = resultElement.Element(web + "Url").Value;
    object resultTitle = resultElement.Element(web + "Title").Value;
 
    Globals.ThisAddIn.Application.ActiveDocument.Hyperlinks.Add(selectedText.Range,
                                            ref resultUrl,
                                            ref missing,
                                            ref resultTitle,
                                            ref missing,
                                            ref missing); 

Zdrojové kódy

K dispozici ke stažení máte zdrojové kódy s příklady z článku: Live Search API (ZIP 1835685 bytů).

Závěr

Webovou službu Live Search API, a většinu dalších, můžete používat nejen pro vytváření webových aplikací, ale také při vytváření aplikací jiných typů.


Autorem článku je Štěpán Bechynský, specialista pro vývojové nástroje ve společnosti Microsoft v České republice. Informace pro vývojáře také najdete na blogu odborníků z českého Microsoftu.

Používáte Live Search API?

Věděli jste, že nám můžete zasílat zprávičky? (Jen pro přihlášené.)

Zdroj: https://www.zdrojak.cz/?p=2961