Différences

Cette page vous donne les différences entre la révision choisie et la version actuelle de la page.

hub_recherche:start [2015/04/22 09:07]
 hub_recherche:start [2018/04/23 11:22] (version actuelle)
Ligne 1: Ligne 1:
 +====== HUB Numérique : API de Recherche ======
 +Le Web service de recherche permet d’interroger la base des livres numériques. Il offre deux possibilités :
 +  * Une recherche multicritères dite recherche rapide : **quickSearch**
 +  * Une recherche détaillée par champ : **advancedSearch**
 +
 +Le Web service search est disponible uniquement en version SOAP.
 +
 +===== Gestion des versions de l'API de Recherche =====
 +A chaque évolution importante de l'API de recherche (par exemple la modification du WSDL : ajout de nouveaux services, ...), le service passe de la version N à la version N+1. Le numéro de version commence par le numéro 1. Ce numéro est visible dans les URL(s) des services. La syntaxe est la suivante :
 +
 +**[ [[:start#les_differentes_plateformes_gerees_par_le_hub|Nom de la plateforme]]]/v[ [[hub_recherche:start#versions_de_l_api_de_recherche|numéro de version]] ]/hub-numerique/[nom de service]**
 +
 +==== Versions de l'API de Recherche ====
 +^Numéro de version^Statut^URL WSDL^Date de mise en production^Date de désactivation de la version^Modifications^
 +|1|Actif|v1|  09-10-2012  |  30-06-2015  |[[historique_des_modifications_recherche:v1|historiques de modification v1]]|
 +|2|Actif|v2|  13-01-2014   |  30-06-2015  |[[historique_des_modifications_recherche:v2|historiques de modification v2]]|
 +|3|Actif|v3|  05-02-2015  | | [[historique_des_modifications_recherche:v3|historiques de modification v3]] |
 +
 +==== Adresses de l'API de Recherche====
 +
 +**Version SOAP :** le WSDL est disponible via l'URL suivant :
 +
 +  * plateforme de test: https://hub-test.centprod.com/v[ [[hub_recherche:start#versions_de_l_api_de_recherche|numéro de version]] ]/hub-numerique/hub-numerique-services-search.wsdl
 +  * plateforme de production: https://hub-dilicom.centprod.com/v[ [[hub_recherche:start#versions_de_l_api_de_recherche|numéro de version]] ]/hub-numerique/hub-numerique-services-search.wsdl
 +
 +Exemple :
 +    * version n°3 (Plateforme de production) : https://hub-dilicom.centprod.com/v3/hub-numerique/hub-numerique-services-search.wsdl
 +    * version n°3 (Plateforme de test) : https://hub-test.centprod.com/v3/hub-numerique/hub-numerique-services-search.wsdl
 +
 +
 +**Version REST :**  Cette version n'est pas implémentée.
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +====== Description de l'API =====
 +
 +Un seul service est disponible, il permet d'effectuer une recherche rapide ou une recherche avancée.
 +
 +
 +===== Interogation du Web Service  =====
 +Requete ''SearchRequest'' :
 +
 +^ glnReseller    | Votre code d'accès | Obligatoire, numérique, 13 caractères       |
 +^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       |
 +^ pagination   | Liste d'éléments ''checkAvailabilityLine'' spécifiant les  disponibilités à vérifier  | Obligatoire   //(cf. ci-dessous)//   |
 +^ catalog  |Ce paramètre permet de limiter la recherche au périmètre de catalogue HUB et/ou [[https://pnb-dilicom.centprod.com/documentation/|PNB]]| Obligatoire, les differents valeurs possibles sont : <html><ul><li><code>HUB</code></li><li><code>PNB</code></li></ul></html>Le paramètre ''catalog'' peut être présent deux fois dans la requête|
 +^ quickSearch  | Champ de recherche rapide, //cf. ci-dessous. //|Obligatoire si l'élément ''advancedSearch'' n'est pas spécifié, texte, maximum 100 caractères  |
 +^ advancedSearch  |Éléments de recherche avancée, //cf. ci-dessous. // |Obligatoire si l'élément ''quickSearch''  n'est pas spécifié |
 +
 +Élément ''pagination'' :
 +^nbResultsPerPage | Nombre de résultats par page souhaité |Facultatif, entier entre 1 et 30, par défaut ''15'' |
 +^currentPage  | Numéro de page sur laquelle on veut se positionner, commence à 1 |Facultatif, par défaut ''1'' |
 +^sortBy  |Clef de tri | Facultatif<html><ul>
 +<li><code>RELEVANCE</code> (pertinence) - par défaut</li>
 +<li><code>EAN13</code></li>
 +<li><code>TITLE</code> (titre)</li>
 +<li><code>PUBLISHER</code> (éditeur)</li>
 +<li><code>DISTRIBUTOR</code> (distributeur)</li>
 +<li><code>AUTHOR</code>  (auteur)</li>
 +<li><code>AVAILABILITY</code>  (disponibilité)</li>
 +<li><code>PUBLICATION_DATE</code> (date de parution)</li>
 +<li><code>PRICE</code> (prix)</li></ul></html>|
 +^sortOrder  |Ordre du critère de tri  |Facultatif<html><ul><li><code>ASCENDING</code> (croissant) - par défaut</li><li><code>DESCENDING</code> (décroissant)</li></ul></html> |
 +
 +Élément ''includeNotice'' :
 +^includeNotice  | Indique si l'on souhaite obtenir le contenu de notices ONIX en réponse, ou seulement les identifiants (ean13, glnDistributor) des fiches.| Facultatif, boolean<html>
 +<ul>
 +<li><code>false</code> - par défaut</li>
 +<li><code>true</code></li>
 +</ul></html> |
 + 
 +
 +==== Recherche rapide  ====
 +Recherche indifféremment sur tous les champs indexés (titre, auteur, EAN, distributeur, thèmes ...)
 +
 +Champ ''quickSearch'' :
 +^quickSearch  | Mot(s) ou code(s) recherché(s) |Obligatoire, texte, maximum 100 caractères  |
 +
 +⇒ [[examples_soap#recherche_rapide|Exemple SOAP de recherche Rapide]]
 +
 +==== Recherche avancée  ====
 +Permet une recherche détaillée par champ.
 +
 +
 +Element ''advancedSearch'' :
 +^availability   | Permet de filtrer sur les articles disponibles ou à paraitre sur la base des valeurs (liste 65)  de la balise Product availability de la notice Onix | Facultatif<html>
 +<ul>
 +<li><code>ORDERABLE</code> (20, 22, 33)</li>
 +<li><code>NOT_YET_AVAILABLE</code> (10)</li>
 +</ul></html>|
 +^title  |Élément(s) de titre recherché(s) |Facultatif, texte, maximum 100 caractères   |
 +^author  |Élément(s) d'auteur recherché(s) |Facultatif, texte, maximum 100 caractères   |
 +^publisher  |Élément(s) d’éditeur recherché(s) |Facultatif, texte, maximum 100 caractères   |
 +^distributor  |Élément(s) de titre recherché(s) |Facultatif, texte, maximum 100 caractères   |
 +^ean13  |Ean recherché, si le champ est renseigné le hub répondra sur ce seul champ en ignorant les autres critères. |Facultatif, texte, maximum 100 caractères   |
 +^publicationSince   | Permet de filtrer les articles sur la base de leur date de parution transmise dans la balise PublishingDate de la notice Onix | Facultatif<html>
 +<ul>
 +<li><code>1_WEEK</code> 1 semaine</li>
 +<li><code>1_MONTH</code> 1 mois</li>
 +<li><code>3_MONTHS</code> 3 mois</li>
 +<li><code>6_MONTHS</code> 6 mois</li>
 +<li><code>1_YEAR</code> 1 an</li>
 +</ul></html> |
 +^keywords  |Recherche dans les libellés présents dans les balises <subjects/> (thèmes CLIL, mots clefs...) |Facultatif, texte, maximum 100 caractères   |
 +
 +=> [[examples_soap#recherche_avancee| Exemple SOAP de recherche avancée ]]
 +
 +==== Réponse du web service ====
 +Réponse ''SearchResponse'' :
 +^requestId  | Identifiant de la requête | Facultatif, alphanumérique |
 +^paginationRs  | Détail de pagination des résultats | //cf. ci-dessous// |
 +^returnStatus  | Statut de la reponse | //cf. [[hub_recherche:start#codes_de_retour|Codes de retour]]// |
 +^returnMessage[]  |Message(s) d'erreur(s) |Facultatif |
 +^detailNotice[]  | Liste des fiches correspondant à la recherche et à la page demandée. | //cf. ci-dessous//|
 +
 +Element ''paginationRs'':
 +^nbResultsPerPage  |Nombre de résultats par page|Numérique |
 +^currentPage  | Page retournée, commence à 1 |Numérique |
 +^sortBy  | Clef de tri | <html><ul>
 +<li><code>RELEVANCE</code> (pertinence) </li>
 +<li><code>EAN13</code></li>
 +<li><code>TITLE</code> (titre)</li>
 +<li><code>PUBLISHER</code> (éditeur)</li>
 +<li><code>DISTRIBUTOR</code> (distributeur)</li>
 +<li><code>AUTHOR</code>  (auteur)</li>
 +<li><code>AVAILABILITY</code>  (disponibilité)</li>
 +<li><code>PUBLICATION_DATE</code> (date de parution)</li>
 +<li><code>PRICE</code> (prix)</li></ul></html>|
 +^sortOrder  |Ordre du critère de tri  |<html><ul><li><code>ASCENDING</code> (croissant)</li><li><code>DESCENDING</code> (décroissant)</li></ul></html> |
 +^nbFoundResults  |Nombre total de fiches correspondant à la recherche |Numérique |
 +^nbSentResults  |Nombre de fiches retournées dans la page courante.| Numérique|
 +
 +Elements ''detailNotice'' :
 +^ean13  | EAN13 de la fiche |Numérique sur 13 |
 +^glnDistributor   | GLN13 du distributeur de la fiche |Numérique sur 13 |
 +^supplierName  | Nom du distributeur de la fiche |Texte |
 +^onixProduct  | Notice ONIX (XML) de la fiche sous forme d'une chaine de caractères.| Présent uniquement si l’élément ''includeNotice'' était spécifié à ''true'' dans la requête. |
 +^type  |Le type de notice|Obligatoire, les différents valeurs possibles sont : <html><ul><li><code>HUB</code></li><li><code>PNB</code></li></ul></html> |
 +
 +==== Codes de retour ====
 +
 +La liste des codes de retour générée par le service search est la suivante :
 +  * OK,
 +  * ACCES_DENIED
 +Le tableau ci-dessous décrit en détail les codes de retour spécifiques au service search:
 +^ Code (returnStatus)^ Message (returnMessage)^Niveau de l'erreur dans la requête ^Cause^
 +| OK| |Requête |La requête est traitée sans erreur|
 +|ERROR | |Requête |Une erreur non spécifiée a eu lieu. |
 +|INVALID_ARGUMENTS | |Requête | Les argument indiqués sont erronés, ou bien certains paramètres obligatoires ne sont pas renseignés|
 +|AUTHENTICATION_ERROR|Bad credentials  |Requête | Erreur d'authentification|
 +|ACCES_DENIED|Authorization failure|Requête |L’utilisateur n’a pas le droit d’accès au service search|
 +|ACCES_DENIED|You are not allowed to search in catalog HUB|Requête|L'utilisateur n'est pas autorisé à effectuer des recherches dans le catalogue HUB|
 +|ACCES_DENIED|You are not allowed to search in catalog PNB|Requête|L'utilisateur n'est pas autorisé à effectuer des recherches dans le catalogue PNB|
 +| ACCES_DENIED|You are not allowed to search in catalog HUB from this GlnDistributeur |Requête |Le paramètre ''advancedSearch.distributor'' est renseigné en format GLN13 et l'utilisateur n'est pas autorisé à effectuer des recherches dans le catalogue HUB de ce distributeur|
 +| ACCES_DENIED|You are not allowed to search in catalog PNB from this GlnDistributeur |Requête |Le paramètre ''advancedSearch.distributor'' est renseigné en format GLN13 et l'utilisateur n'est pas autorisé à effectuer des recherches dans le catalogue PNB de ce distributeur|