Edurep:SMO SearchRetrieve

Uit Kennisnet Developers Documentatie
Versie door Muskee01 (overleg | bijdragen) op 18 nov 2013 om 09:52 (done)
Naar navigatie springen Naar zoeken springen

Edurep-symbol.png Edurep: SMO SearchRetrieve

SMO data kan in Edurep worden opgevraagd via een SRU of SRW endpoint, gebruik makend van de CQL query taal. Op deze pagina staat een overzicht van de specifieke implementatie van SRU/SRW voor de SMO endpoints.

Endpoints

Argumenten

Een overzicht van de ondersteunde argumenten:

naam # type omschrijving
version 1 tekst 1.2
query 1 cql query Een zoekopdracht binnen SMO records Lees meer.
startRecord 0-1 getal De resultatenlijst wordt getoond vanaf dit record, standaard 1. Lees meer.
maximumRecords 0-1 getal Het aantal records in de getoonde resultatenlijst, standaard 10, max 100 Lees meer.
recordPacking 0-1 tekst Het formaat waarin de resultatenlijst wordt teruggegeven Lees meer.
x-term-drilldown 0-1 lom veld Het veld waarop een term drilldown wordt gedaan voor de gevonden resultaten Lees meer.


Voorbeeld Verzoek

http://smb.edurep.kennisnet.nl:8000/smo/sruns?version=1.2&operation=searchRetrieve&query=leuk&startRecord=1&maximumRecords=5

Voorbeeld Respons

<srw:searchRetrieveResponse>
  <srw:version>1.2</srw:version>
  <srw:numberOfRecords>1267</srw:numberOfRecords>
  <srw:records>
    <srw:record>
      <srw:recordSchema>lom</srw:recordSchema>
      <srw:recordPacking>xml</srw:recordPacking>
      <srw:recordIdentifier>Leraar24_smo_comment:comment:21798</srw:recordIdentifier>
      <srw:recordData>
        ...
        <!-- Hier staat een gevonden record. -->
        ...
      </srw:recordData>
    </srw:record>
  </srw:records>
  <srw:nextRecordPosition>6</srw:nextRecordPosition>
  <srw:echoedSearchRetrieveRequest>
    <srw:version>1.2</srw:version>
    <srw:query>leuk</srw:query>
    <srw:startRecord>1</srw:startRecord>
    <srw:recordPacking>string</srw:recordPacking>
    <srw:recordSchema>smo</srw:recordSchema>
  </srw:echoedSearchRetrieveRequest>
</srw:searchRetrieveResponse>

Eigenschappen

Bij het maken van een koppeling op de zoekinterface van Edurep, dient men rekening te houden met een aantal eigenschappen.

Overbelasting

Het kan voorkomen dat Edurep overbelast is door een teveel aan binnenkomende requests. Deze faciliteit is ingebouwd om te voorkomen dat de responstijden teveel oplopen. In dat geval zal Edurep een HTTP 503 statuscode terugsturen. Het is raadzaam bij de implementatie met deze statuscode rekening te houden en het na een korte pauze opnieuw te proberen. Kans is heel groot dat Edurep dan weer een slot beschikbaar heeft. Voor meer informatie over de HTTP 503 melding bekijk de officiële definitie op W3C.

Compressie

De xml responses van Edurep kunnen gecomprimeerd worden verstuurd. Edurep ondersteunt de zogenaamde "deflate" en "gzip" compressie methoden voor content-encoding. De antwoorden van Edurep worden gecomprimeerd (min. 90%), waardoor het transport van alle XML geen vertragende factor meer is. De impact van het in- en uitpakken is nihil, dus de winst maximaal. De meeste browsers ondersteunen dit tegenwoordig standaard maar in backend code moet dit expliciet worden aangezet. Bijvoorbeeld in PHP-cURL gebeurt dit door het zetten van een cURL-optie: curl_setopt($curl, CURLOPT_ENCODING, 'gzip,deflate');.

Relevantie

Edurep bevat drie soorten velden met elk specifieke mogelijkheden voor het zoeken:

  • vrije tekstvelden: voor bepaling relevantie
  • vocabulaire velden: voor het filteren van de resultatenset
  • numerieke velden: voor het sorteren van de resultatenset

Wanneer in de zoekopdracht geen beperkingen worden aangegeven, worden de resultaten in principe in willekeurige volgorde teruggegeven. De plek van een record in deze willekeurige lijst wordt bij het harvesten van het record bepaald.

Het gebruik van filters (bijv. context=PO) heeft geen invloed op de willekeurige volgorde waarmee de records worden teruggegeven. Wanneer meerdere filters in een OR query worden gesteld, zullen de records die aan alle filters voldoen relevanter zijn en dus hoger in de resultatenlijst komen.

De daadwerkelijke relevantiebepaling wordt gedaan aan de hand van de zoekopdrachten in vrije tekstvelden. De relevantie wordt dan bepaald aan de hand van de relatieve voorkomendheid van de zoekwoorden in een record. Er wordt bijvoorbeeld gezocht op "fiets". Een record met 100 trefwoorden (waarvan 1x fiets) zal minder relevant zijn dan een record met 5 trefwoorden (waarvan 1x fiets).

Spiders

Zoekmachines als Google en Yahoo maken gebruik van programma's die geautomatiseerd het internet afzoeken en de gevonden pagina's indexeren. Het kan voorkomen dat deze spiders via de gebouwde zoekapplicatie zoekopdrachten aan Edurep stellen. Dit type zoekopdrachten zorgen voor een oneigenlijk gebruik van Edurep. Het vervuilt niet alleen de statistieken van Edurep maar ook de statistieken van de betreffende zoekapplicatie.

Er zijn verschillende manieren om de toegang voor spiders op de website te beperken, zodanig dat alleen het zoekdeel van de applicatie voor de spiders wordt afgesloten. Een overzicht hiervan is te vinden op Wikipedia.


Foutmeldingen

SRU Foutmeldingen

Een foutmelding vanuit Edurep is te herkennen aan de aanwezigheid van het diagnostics veld. In dit veld zal dan een diagnostic staan die die volgende elementen bevat:

  • een foutcode: in diagnostic/uri
  • een titel: in diagnostic/message
  • een beschrijving: in diagnostic/details

Voorbeeld

<srw:searchRetrieveResponse>
  <srw:version>1.2</srw:version>
  <srw:numberOfRecords>0</srw:numberOfRecords>
  <srw:diagnostics>
    <diagnostic>
      <uri>info://srw/diagnostics/1/48</uri>
      <details>Unexpected token after parsing ([=], CQL_QUERY(SCOPED_CLAUSE(SEARCH_CLAUSE(SEARCH_TERM(TERM('test')))))).</details>
      <message>Query Feature Unsupported</message>
    </diagnostic>
  </srw:diagnostics>
</srw:searchRetrieveResponse>

Foutcodes

foutcode titel/message uitleg
info://srw/diagnostics/1/4 Unsupported Operation Alleen operaties searchRetrieve en explain worden ondersteund.
info://srw/diagnostics/1/5 Unsupported Version Alleen versies 1.1 en 1.2 worden ondersteund. Gebruik 1.2
info://srw/diagnostics/1/6 Unsupported Parameter Value De waarde van een query parameter is ongeldig.
info://srw/diagnostics/1/7 Mandatory Parameter Not Supplied Niet alle verplichte argumenten zijn meegegeven.
info://srw/diagnostics/1/8 Unsupported Parameter Een van de query parameters is ongeldig.
info://srw/diagnostics/1/12 Too many characters in query Het query argument mag maximaal 4096 tekens bevatten.
info://srw/diagnostics/1/48 Query Feature Unsupported De query bevat een fout.


Jsonsearch Foutmeldingen

Een foutmelding uit de jsonsearch is te herkennen aan de "error" key in de response.

Voorbeeld

{
    "error": {
        "message": "Missing required argument: 'query'",
        "type": "MissingArgument"
    },
    "version": "0.1.beta"
}

Foutcodes

type omschrijving
MissingArgument een vereist argument ontbreekt in het verzoek
Overgenomen van "https://developers.wiki.kennisnet.nl/index.php?title=Edurep:SMO_SearchRetrieve&oldid=506"