CS:Entry SearchRetrieve: verschil tussen versies

Uit Kennisnet Developers Documentatie
Ga naar: navigatie, zoeken
(add response example)
(Argumenten)
 
(17 tussenliggende versies door 2 gebruikers niet weergegeven)
Regel 1: Regel 1:
Catalogus Service entry data kan worden opgevraagd via een {{Standaard|SRU}}, gebruik makend van de [[Edurep:CQL|CQL]] query taal. Op deze pagina staat een overzicht van de specifieke implementatie van SRU.
+
Catalogus Service entry data kan worden opgevraagd via een {{Standaard|SRU}}, gebruik makend van de [[Standaarden:SRU/Edurep CQL|CQL]] query taal.
  +
Op deze pagina staat een overzicht van de specifieke implementatie van SRU.
  +
Er is ook een aparte pagina met [[CS:Veldenlijst|een overzicht van alle zoekvelden]].
   
 
== Endpoint ==
 
== Endpoint ==
* SRU: https://catalogusservice.edurep.nl/sru
+
* SRU Productie: https://catalogusservice.edurep.nl/sru
  +
* SRU Staging: https://staging.catalogusservice.edurep.nl/sru
   
 
== Argumenten ==
 
== Argumenten ==
Een overzicht van de ondersteunde argumenten. De in SRU verplichte argumenten ''operation'' en ''version'' zijn optioneel.
+
Een overzicht van de ondersteunde argumenten.
  +
{{Info|Het wordt sterk geadviseerd om altijd het recordSchema argument te gebruiken met een versie.}}
 
{| class="wikitable"
 
{| class="wikitable"
 
! naam
 
! naam
Regel 15: Regel 19:
 
|1
 
|1
 
|cql query
 
|cql query
|Een zoekopdracht binnen LOM records [[Edurep:LOM_SearchRetrieve/query|Lees meer]].
+
|Een zoekopdracht binnen LOM records.
 
|-
 
|-
 
|startRecord
 
|startRecord
 
|0-1
 
|0-1
 
|getal
 
|getal
|De resultatenlijst wordt getoond vanaf dit record, standaard 1. [[Edurep:LOM_SearchRetrieve/startRecord|Lees meer]].
+
|De resultatenlijst wordt getoond vanaf dit record, standaard 1.
 
|-
 
|-
 
|maximumRecords
 
|maximumRecords
 
|0-1
 
|0-1
 
|getal
 
|getal
|Het aantal records in de getoonde resultatenlijst, standaard 10, max 100 [[Edurep:LOM_SearchRetrieve/maximumRecords|Lees meer]].
+
|Het aantal records in de getoonde resultatenlijst, standaard 10, max 100.
  +
|-
  +
|recordSchema
  +
|0-1
  +
|tekst
  +
|De versie van het record wat wordt teruggegeven.
  +
|-
  +
|x-recordSchema
  +
|0-*
  +
|tekst
  +
|Een extra type record wat kan worden meegegeven.
  +
|-
  +
|x-term-drilldown
  +
|0-1
  +
|edurep zoekveld
  +
|Het veld waarop een [[#Drilldown|term drilldown]] wordt gedaan voor de gevonden resultaten.
  +
|-
  +
|sortKeys
  +
|0-1
  +
|edurep zoekveld
  +
|Het veld waarop [[#Sortering|gesorteerd]] moeten worden.
  +
|-
  +
|recordPacking
  +
|0-1
  +
|tekst
  +
|Het formaat waarin de resultatenlijst wordt teruggegeven [[Standaarden:SRU/recordPacking|Lees meer]].
  +
|-
  +
|operation
  +
|0-1
  +
|tekst
  +
|searchRetrieve
  +
|-
  +
|version
  +
|0-11
  +
|tekst
  +
|1.2
 
|-
 
|-
 
|}
 
|}
   
== Voorbeeld SRU-Verzoek ==
+
=== Query ===
  +
{{:Edurep:Zoekopdracht/Query}}
<nowiki>https://catalogusservice.edurep.nl/sru?query=boek&startRecord=1&maximumRecords=5</nowiki>
 
  +
=== Paginering ===
  +
{{:Edurep:Zoekopdracht/Paginering}}
  +
{{:Edurep:Zoekopdracht/Paginering/SRU}}
  +
=== Drilldown ===
  +
{{:Edurep:Zoekopdracht/Drilldown}}
  +
{{:Edurep:Zoekopdracht/Drilldown/SRU}}
  +
=== Sortering ===
  +
{{:Edurep:Zoekopdracht/Sortering}}
  +
{{:Edurep:Zoekopdracht/Sortering/SRU}}
  +
=== recordSchema ===
  +
De waarde van recordSchema bepaalt in welk formaat een resultaat wordt teruggegeven. Standaard wordt 1 [[CS:Versies|versie]] van ''eckcs'' teruggegeven.
  +
Aangezien de standaard elk moment gewijzigd kan worden wordt aangeraden altijd een recordSchema mee te geven.
  +
{| class="wikitable"
  +
! recordSchema
  +
! omschrijving
  +
|-
  +
|eckcs2.3
  +
|Entry versie 2.3
  +
|-
  +
|eckcs2.4
  +
|Entry versie 2.4
  +
|-
  +
|meta
  +
|technische informatie van record
  +
|-
  +
|}
  +
{{CatalogusServiceQuery|query=boek|schema=meta}}
   
 
== Voorbeeld Respons ==
 
== Voorbeeld Respons ==
Regel 74: Regel 140:
 
</srw:searchRetrieveResponse>
 
</srw:searchRetrieveResponse>
 
</syntaxhighlight>
 
</syntaxhighlight>
  +
  +
== Foutmeldingen ==
  +
{{:Edurep:Foutmeldingen/SRU}}
  +
  +
[[Categorie:Catalogus Service]]

Huidige versie van 21 okt 2021 om 04:16

Catalogus Service entry data kan worden opgevraagd via een SRU, gebruik makend van de CQL query taal. Op deze pagina staat een overzicht van de specifieke implementatie van SRU. Er is ook een aparte pagina met een overzicht van alle zoekvelden.

Endpoint

Argumenten

Een overzicht van de ondersteunde argumenten.

Info.gif Het wordt sterk geadviseerd om altijd het recordSchema argument te gebruiken met een versie.
naam # type omschrijving
query 1 cql query Een zoekopdracht binnen LOM records.
startRecord 0-1 getal De resultatenlijst wordt getoond vanaf dit record, standaard 1.
maximumRecords 0-1 getal Het aantal records in de getoonde resultatenlijst, standaard 10, max 100.
recordSchema 0-1 tekst De versie van het record wat wordt teruggegeven.
x-recordSchema 0-* tekst Een extra type record wat kan worden meegegeven.
x-term-drilldown 0-1 edurep zoekveld Het veld waarop een term drilldown wordt gedaan voor de gevonden resultaten.
sortKeys 0-1 edurep zoekveld Het veld waarop gesorteerd moeten worden.
recordPacking 0-1 tekst Het formaat waarin de resultatenlijst wordt teruggegeven Lees meer.
operation 0-1 tekst searchRetrieve
version 0-11 tekst 1.2

Query

In Edurep kan er worden gezocht op AND/OR/NOT combinaties van trefwoorden, binnen de totale set of binnen specifieke velden.

  • fiets AND pomp
  • kasteel AND (ridder OR ridders)
  • vis AND walvis NOT potvis
  • breuken AND vak=wiskunde
  • breuken AND (titel=werkblad OR titel=taak)

Afhankelijk van de gebruikte zoekinterface zijn er verschillende zoekvelden beschikbaar, bekijk de veldenlijst voor een overzicht.

Voorbeelden:

/edurep/sruns: query=fiets AND pomp
/smo/sruns: query=smo.hReview.info exact "http://wikiwijs.samendelen.nl/get/smpid:5585/DS1"
Catalogus Service: query=Title=techniek AND Price<500
/jsonsearch: query=fiets AND schema:name="werkblad"

Beperkingen:

  • De waarde van het query argument mag maximaal 4096 tekens zijn, na urldecoding.
  • De zoekwoorden kunnen alleen letters en cijfers bevatten. Vanwege het indexatieproces zijn speciale karakters als # en $ zijn niet doorzoekbaar.
  • Wildcard zoeken is beperkt mogelijk. Zoeken op fiets* is wel mogelijk maar *fiets niet. De fiets* is mogelijk met minimaal 2 karakters. Het zoeken met het wildcard teken in een string (infix) is ook mogelijk, ook met minimaal 2 voorloopkarakters. Er mag maximaal 1 * voorkomen per trefwoord.

Paginering

Edurep resultaten worden gepagineerd aangeboden. Standaard worden de eerste 10 teruggegeven, en het is met parameters mogelijk om de verschillende pagina's van de totale resultatenset op te halen (tot een maximum van 4000). Bij een startRecord hoger, wordt een foutmelding meegegeven, maar wordt de laatste pagina getoond (alsof de startRecord gelijk is aan 4000).

Paginering in SRU werkt met de volgende argumenten:

  • startRecord
  • maximumRecords

Met maximumRecords kan het aantal resultaten per pagina worden ingesteld, en met startRecord wordt aangegeven wat het eerste record van de resultatenset is.

/edurep/sruns: query=feest&maximumRecords=20&startRecord=21
Catalogus Service: query=rekenen&maximumRecords=20&startRecord=21

Drilldown

Met een optionele term drilldown worden alle waarden van een bepaald veld cumulatief geteld over alle zoekresultaten. Dit kan slechts op een beperkt aantal velden. Er kunnen meerdere term drilldowns gedaan worden per search request door de velden te scheiden met een komma.

Het gewenste aantal resultaten in de drilldown kan worden aangegeven door ":<nummer>" aan de drilldown term toe te voegen. Als je ":0" toevoegt worden alle drilldown resultaten getoond.

De volgorde van de termen met een gelijk aantal kan verschillen per zoekopdracht. De sortering komt namelijk voort uit hoe het drilldown algoritme werkt. Voor elementen met dezelfde waarde is geen volgorde gedefinieerd omdat dit efficiënter is en weinig toegevoegde waarde heeft.

Een drilldown kan in SRU met het x-term-drilldown argument worden meegegeven.

/edurep/sruns: query=oostenrijk&x-term-drilldown=lom.general.language:5,lom.technical.format
/smo/sruns: query=leuk&x-term-drilldown=smo.supplierId
Catalogus Service: query=aardrijkskunde&x-term-drilldown=Supplier

Response

<dd:drilldown xmlns:dd="http://meresco.org/namespace/drilldown"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://namespace.meresco.org/drilldown http://namespace.drilldown.org/xsd/drilldown.xsd">
  <dd:term-drilldown>
    <dd:navigator name="lom.educational.context.value">
      <dd:item count="921">VO</dd:item>
      <dd:item count="319">BVE</dd:item>
      <dd:item count="221">PO</dd:item>
      <dd:item count="33">primaire onderwijs</dd:item>
      <dd:item count="26">beroepsonderwijs en volwasseneneducatie</dd:item>
      <dd:item count="26">speciaal onderwijs</dd:item>
      <dd:item count="24">voortgezet onderwijs</dd:item>
      <dd:item count="16">speciaal basisonderwijs</dd:item>
      <dd:item count="13">wetenschappelijk onderwijs</dd:item>
      <dd:item count="12">VVE</dd:item>
    </dd:navigator>
    <dd:navigator name="lom.rights.cost">
      <dd:item count="1160">no</dd:item>
      <dd:item count="38">yes</dd:item>
    </dd:navigator>
    <dd:navigator name="lom.technical.format"/>
  </dd:term-drilldown>
</dd:drilldown>
naam # type omschrijving
term-drilldown 1 container De term-drilldown container.
navigator 1+ container De navigator container. Bevat alle facets voor het betreffende veld.
item 0+ tekst De naam van de facet. Het aantal staat in het count attribuut.

Sortering

Er zijn is Edurep verschillende velden waarop gesorteerd kan worden. Standaard wordt de sortering van de zoekmachine aangehouden, en dat is op de door de zoekmachine bepaalde relevantie. Per veld kan er ascending of descending gesorteerd worden.

Het SRU/SRW protocol (versie 1.1) gebruikt het argument sortKeys om een gewenste sortering door te geven. Het is vervolgens mogelijk om in de implementatie aan te geven of het veld oplopend of aflopend wordt gesorteerd. Dit gebeurt door een boolean met de waarde 0 of 1.

Oplopend:

/edurep/sruns: query=beatrix&sortKeys=lom.lifecycle.contribute.publisherdate,,0

Aflopend:

/edurep/sruns: query=beatrix&sortKeys=lom.lifecycle.contribute.publisherdate,,1

recordSchema

De waarde van recordSchema bepaalt in welk formaat een resultaat wordt teruggegeven. Standaard wordt 1 versie van eckcs teruggegeven. Aangezien de standaard elk moment gewijzigd kan worden wordt aangeraden altijd een recordSchema mee te geven.

recordSchema omschrijving
eckcs2.3 Entry versie 2.3
eckcs2.4 Entry versie 2.4
meta technische informatie van record
Catalogus Service: query=boek&recordSchema=meta

Voorbeeld Respons

<srw:searchRetrieveResponse xmlns:srw="http://www.loc.gov/zing/srw/">
  <srw:version>1.2</srw:version>
  <srw:numberOfRecords>117</srw:numberOfRecords>
  <srw:records>
    <srw:record>
      <srw:recordSchema>eckcs2.1.1</srw:recordSchema>
      <srw:recordPacking>xml</srw:recordPacking>
      <srw:recordIdentifier>test:59</srw:recordIdentifier>
      <srw:recordData>
        <Entry xmlns="http://dt2.eck.nl/schema/catalogservice/v2.1.1" xmlns:ct="http://dt2.eck.nl/schema/common/v2.1">
          <ProductId>59</ProductId>
          <Publisher>Kennisnet</Publisher>
          <PublisherThumbnailLocation>https://pbs.twimg.com/profile_images/638314278882140163/zWL5qqYc_400x400.png</PublisherThumbnailLocation>
          <Title>Price Test 1</Title>
          <Authors>
            <Author>Kennisnet</Author>
          </Authors>
          <IntendedEndUserRole>Beheerder</IntendedEndUserRole>
          <IsConsumptionProduct>false</IsConsumptionProduct>
          <SaleUnitSize>1</SaleUnitSize>
          <Currency>EURO</Currency>
          <PriceVATHigh>4300</PriceVATHigh>
          <PriceVATLow>500</PriceVATLow>
          <IsLicensed>false</IsLicensed>
        </Entry>
      </srw:recordData>
    </srw:record>
    <!-- meer records -->
  </srw:records>
  <srw:nextRecordPosition>6</srw:nextRecordPosition>
  <srw:echoedSearchRetrieveRequest>
    <srw:version>1.2</srw:version>
    <srw:query>boek</srw:query>
    <srw:startRecord>1</srw:startRecord>
    <srw:maximumRecords>10</srw:maximumRecords>
    <srw:recordPacking>xml</srw:recordPacking>
    <srw:recordSchema>eckcs2.1.1</srw:recordSchema>
  </srw:echoedSearchRetrieveRequest><srw:extraResponseData>
</srw:searchRetrieveResponse>

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.