Standaarden:ECK-DT: verschil tussen versies

Uit Kennisnet Developers Documentatie
Naar navigatie springen Naar zoeken springen
(first)
 
(v 2.5.2)
 
(15 tussenliggende versies door 2 gebruikers niet weergegeven)
Regel 1: Regel 1:
  +
Digitale leermiddelen nemen ieder jaar een belangrijkere plaats in op de leermiddelenlijst van onderwijsinstellingen.<br/>
  +
Voor een foutloze distributie en toegang van digitale leermiddelen zijn uitgevers, distributeurs en leveranciers van elektronische leeromgevingen en leerlingadministratiesystemen afhankelijk van elkaar.
  +
  +
De afspraak '''ECK Distributie en toegang''' maakt allerlei vormen van dienstverlening binnen de '''Educatieve Contentketen (ECK)''' mogelijk.<br/>
  +
De afspraak omvat een referentiearchitectuur met daarin relevante begrippen, de gehanteerde principes en een beschrijving van de processen, een '''beschrijving van de Web Services''' en technische voorschriften.
  +
 
== Documentatie ==
  
== Documentatie ==
−
{{Documentatie|https://www.edustandaard.nl/standaard_afspraken/eck-distributie-en-toegang/|Afspraak bij Edustandaard|nl|referentie}}
 +
{{Documentatie|https://www.edustandaard.nl/standaard_afspraken/eck-distributie-en-toegang/|Afspraak ECK Distributie en toegang bij Edustandaard|nl|laatste versie}}
  +
  +
<br/>
  +
De Edurep CatalogService werkt met maximaal '''[[CS:Versies|2 versies]]''' van de ECK-DT standaard.
  +
  +
[https://www.edustandaard.nl/standaard_afspraken/eck-distributie-en-toegang/eck-distributie-en-toegang-2-5-2/ Versie: '''ECK Distributie en toegang 2.5.2'''] (september 2023)<br/>
  +
* Voor de implementatie van de afspraak versie 2.5.2 kunt u gebruikmaken van [https://www.edustandaard.nl/app/uploads/2023/09/ECK-DT-v2.5.2.zip technische bestanden] (zip-bestand).
  +
  +
[https://www.edustandaard.nl/standaard_afspraken/eck-distributie-en-toegang/eck-distributie-en-toegang-2-5-1/ Versie: '''ECK Distributie en toegang 2.5.1'''] (november 2022)<br/>
  +
* Voor de implementatie van de afspraak versie 2.5.1 kunt u gebruikmaken van [https://www.edustandaard.nl/app/uploads/2022/11/ECK-DT-v2.5.1.zip technische bestanden] (zip-bestand).
   
 
== Onderdelen ==
  
== Onderdelen ==
−
* [[Standaarden:ECK-DT/CatalogService|CatalogService]]
 +
* Web service '''CatalogService'''
  +
* overige web services: ''LicenseService'', ''EducationalContentListService'', ''OrderService'', ''SpecifyService'' en ''ActivationCodeService'' (hier (nog) niet gedocumenteerd)
−
* overige nog niet gedocumenteerd
  
  +
  +
== Metadata en Transport ==
  +
De [[Standaarden:ECK-DT/CatalogService|'''CatalogService''']] web service gaat over de '''metadata''' van de catalogus onderdelen, maar ook het '''transport''' daarvan.
  +
  +
== SOAP ==
  +
Via een '''SOAP endpoint''' worden '''alle''' catalogusinformatie '''aangeboden''' volgens de specificaties van de ECK DT standaard.
  +
  +
De [[Standaarden:SOAP|SOAP]] header vereist een aantal WS-Addressing velden in het verzond en ontvangstbericht.
  +
  +
=== Request ===
  +
Een overzicht van de WS-A argumenten:
  +
{| class="wikitable"
  +
! naam
  +
! #
  +
! type
  +
! omschrijving
  +
|-
  +
|Action
  +
|1
  +
|uri
  +
|de webservice specificatie identifier
  +
|-
  +
|To
  +
|1
  +
|url
  +
|de endpoint waar het bericht naar toe verzonden wordt
  +
|-
  +
|MessageID
  +
|1
  +
|uri
  +
|unieke berichtcode
  +
|-
  +
|From
  +
|1
  +
|wsa:Adress met uri
  +
|afzender in uri waarbij ''OrganisationId'' als verplichte querystring parameter wordt opgenomen, ''wachtwoord'' idem
  +
|-
  +
|}
  +
  +
Aangezien de WSDL (en daarmee ook de SOAP endpoint) feitelijk '''publiek''' staat, is het mogelijk/noodzakelijk de endpoint te beschermen tegen ongeautoriseerde verzoeken.<br/> Om te kunnen herkennen dat een verzoek van CatalogService (hier ontvanger) afkomstig is, moet '''zender/aanbieder''' een ''OrganisationId'' en een ''wachtwoord'' definiëren (in de praktijk zullen zender en ontvanger hier een afspraak over maken).
  +
  +
'''Voorbeeld:'''
  +
<syntaxhighlight lang="xml">
  +
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  +
<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
  +
<wsa:Action soapenv:mustUnderstand="1">http://dt2.eck.nl/service/orderservice/v2.1.1/getstockstatus</wsa:Action>
  +
<wsa:From soapenv:mustUnderstand="1">
  +
<wsa:Address>https://distributeur.nl?organisationid=27244834&amp;password=X</wsa:Address>
  +
</wsa:From>
  +
<wsa:MessageID soapenv:mustUnderstand="1">urn:uuid:1f64216c-ec95-489d-a1c1-0d1ea3656be0</wsa:MessageID>
  +
<wsa:To soapenv:mustUnderstand="1">https://uitgever.nl/OrderService</wsa:To>
  +
</soapenv:Header>
  +
<soapenv:Body>
  +
...
  +
</soapenv:Body>
  +
</soapenv:Envelope>
  +
</syntaxhighlight>
  +
  +
=== Response ===
  +
<syntaxhighlight lang="xml">
  +
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  +
<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
  +
<wsa:Action>http://dt2.eck.nl/service/orderservice/v2.1.1/getstockstatus</wsa:Action>
  +
<!-- De Technische Voorschriften zijn niet volledig duidelijk hierover,
  +
maar de aanname hier is dat het berichtenverkeer synchroon is. -->
  +
<!-- <wsa:RelatesTo RelationshipType="http://www.w3.org/2005/08/addressing/reply">urn:uuid:7f9f9e8c-be3b-4b45-91b6-ce7c437c6967</wsa:RelatesTo> -->
  +
<wsa:To>https://distributeur.nl?organisationid=27244834</wsa:To>
  +
<wsa:MessageID>urn:uuid:0d7acc60-6044-4283-a2be-eb4a50ba4c97</wsa:MessageID>
  +
</soapenv:Header>
  +
<soapenv:Body>
  +
...
  +
</soapenv:Body>
  +
</soapenv:Envelope>
  +
</syntaxhighlight>
  +
  +
=== Foutmeldingen ===
  +
Foutmeldingen worden teruggegeven in de SOAP Body volgens de in de Common xsd beschreven FaultMessage, en gebruik makend van de in de Technische Voorschriften voorziene foutenbijlage.
  +
  +
<syntaxhighlight lang="xml">
  +
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  +
<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
  +
<wsa:Action>http://dt2.eck.nl/service/orderservice/v2.1.1/getstockstatus</wsa:Action>
  +
<wsa:To>https://distributeur.nl?organisationid=27244834</wsa:To>
  +
<wsa:MessageID>urn:uuid:0d7acc60-6044-4283-a2be-eb4a50ba4c97</wsa:MessageID>
  +
</soapenv:Header>
  +
<soapenv:Body>
  +
<soapenv:Fault>
  +
<faultcode>soapenv:client</faultcode>
  +
<faultstring>OrganisationId is niet ingevuld</faultstring>
  +
<detail>
  +
<os:FaultMessage xmlns:c="http://dt2.eck.nl/schema/common/v2.1" os:xmlns="http://dt2.eck.nl/schema/orderservice/v2.1.1">
  +
<c:FaultDescription>OrganisationId is niet ingevuld</c:FaultDescription>
  +
<c:Code>10</c:Code>
  +
</os:FaultMessage>
  +
</detail>
  +
</soapenv:Fault>
  +
</soapenv:Body>
  +
</soapenv:Envelope>
  +
</syntaxhighlight>
  +
  +
Standaard foutcodes voor alle services:
  +
{|class="wikitable"
  +
|-
  +
! foutcode
  +
! titel/message
  +
|-
  +
| -1
  +
| Algemene fout
  +
|-
  +
| -2
  +
| Authenticatiefout
  +
|-
  +
| -200
  +
| Berichtformaat voldoet niet aan specificatie
  +
|-
  +
|}
   
 
[[Categorie:Standaarden]]
  
[[Categorie:Standaarden]]

Huidige versie van 26 jun 2024 om 12:57

Digitale leermiddelen nemen ieder jaar een belangrijkere plaats in op de leermiddelenlijst van onderwijsinstellingen.
Voor een foutloze distributie en toegang van digitale leermiddelen zijn uitgevers, distributeurs en leveranciers van elektronische leeromgevingen en leerlingadministratiesystemen afhankelijk van elkaar.

De afspraak ECK Distributie en toegang maakt allerlei vormen van dienstverlening binnen de Educatieve Contentketen (ECK) mogelijk.
De afspraak omvat een referentiearchitectuur met daarin relevante begrippen, de gehanteerde principes en een beschrijving van de processen, een beschrijving van de Web Services en technische voorschriften.

Documentatie

Bullet book.png Afspraak ECK Distributie en toegang bij Edustandaard Nl.gif (laatste versie)


De Edurep CatalogService werkt met maximaal 2 versies van de ECK-DT standaard.

Versie: ECK Distributie en toegang 2.5.2 (september 2023)

  • Voor de implementatie van de afspraak versie 2.5.2 kunt u gebruikmaken van technische bestanden (zip-bestand).

Versie: ECK Distributie en toegang 2.5.1 (november 2022)

  • Voor de implementatie van de afspraak versie 2.5.1 kunt u gebruikmaken van technische bestanden (zip-bestand).

Onderdelen

  • Web service CatalogService
  • overige web services: LicenseService, EducationalContentListService, OrderService, SpecifyService en ActivationCodeService (hier (nog) niet gedocumenteerd)

Metadata en Transport

De CatalogService web service gaat over de metadata van de catalogus onderdelen, maar ook het transport daarvan.

SOAP

Via een SOAP endpoint worden alle catalogusinformatie aangeboden volgens de specificaties van de ECK DT standaard.

De SOAP header vereist een aantal WS-Addressing velden in het verzond en ontvangstbericht.

Request

Een overzicht van de WS-A argumenten:

naam # type omschrijving
Action 1 uri de webservice specificatie identifier
To 1 url de endpoint waar het bericht naar toe verzonden wordt
MessageID 1 uri unieke berichtcode
From 1 wsa:Adress met uri afzender in uri waarbij OrganisationId als verplichte querystring parameter wordt opgenomen, wachtwoord idem

Aangezien de WSDL (en daarmee ook de SOAP endpoint) feitelijk publiek staat, is het mogelijk/noodzakelijk de endpoint te beschermen tegen ongeautoriseerde verzoeken.
Om te kunnen herkennen dat een verzoek van CatalogService (hier ontvanger) afkomstig is, moet zender/aanbieder een OrganisationId en een wachtwoord definiëren (in de praktijk zullen zender en ontvanger hier een afspraak over maken).

Voorbeeld: 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
        <wsa:Action soapenv:mustUnderstand="1">http://dt2.eck.nl/service/orderservice/v2.1.1/getstockstatus</wsa:Action>
        <wsa:From soapenv:mustUnderstand="1">
            <wsa:Address>https://distributeur.nl?organisationid=27244834&amp;password=X</wsa:Address>
        </wsa:From>
        <wsa:MessageID soapenv:mustUnderstand="1">urn:uuid:1f64216c-ec95-489d-a1c1-0d1ea3656be0</wsa:MessageID>
        <wsa:To soapenv:mustUnderstand="1">https://uitgever.nl/OrderService</wsa:To>
    </soapenv:Header>
    <soapenv:Body>
    ...
    </soapenv:Body>
</soapenv:Envelope>

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
        <wsa:Action>http://dt2.eck.nl/service/orderservice/v2.1.1/getstockstatus</wsa:Action>
        <!-- De Technische Voorschriften zijn niet volledig duidelijk hierover,
             maar de aanname hier is dat het berichtenverkeer synchroon is. -->
        <!-- <wsa:RelatesTo RelationshipType="http://www.w3.org/2005/08/addressing/reply">urn:uuid:7f9f9e8c-be3b-4b45-91b6-ce7c437c6967</wsa:RelatesTo> -->
        <wsa:To>https://distributeur.nl?organisationid=27244834</wsa:To>
        <wsa:MessageID>urn:uuid:0d7acc60-6044-4283-a2be-eb4a50ba4c97</wsa:MessageID>
    </soapenv:Header>
    <soapenv:Body>
    ...
    </soapenv:Body>
</soapenv:Envelope>

Foutmeldingen

Foutmeldingen worden teruggegeven in de SOAP Body volgens de in de Common xsd beschreven FaultMessage, en gebruik makend van de in de Technische Voorschriften voorziene foutenbijlage. 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
        <wsa:Action>http://dt2.eck.nl/service/orderservice/v2.1.1/getstockstatus</wsa:Action>
        <wsa:To>https://distributeur.nl?organisationid=27244834</wsa:To>
        <wsa:MessageID>urn:uuid:0d7acc60-6044-4283-a2be-eb4a50ba4c97</wsa:MessageID>
    </soapenv:Header>
    <soapenv:Body>
        <soapenv:Fault>
            <faultcode>soapenv:client</faultcode>
            <faultstring>OrganisationId is niet ingevuld</faultstring>
            <detail>
                <os:FaultMessage xmlns:c="http://dt2.eck.nl/schema/common/v2.1" os:xmlns="http://dt2.eck.nl/schema/orderservice/v2.1.1">
                    <c:FaultDescription>OrganisationId is niet ingevuld</c:FaultDescription>
                    <c:Code>10</c:Code>
                </os:FaultMessage>
            </detail>
        </soapenv:Fault>
    </soapenv:Body>
</soapenv:Envelope>

Standaard foutcodes voor alle services:

foutcode titel/message
-1 Algemene fout
-2 Authenticatiefout
-200 Berichtformaat voldoet niet aan specificatie
Overgenomen van "https://developers.wiki.kennisnet.nl/index.php?title=Standaarden:ECK-DT&oldid=12999"