Spécification d'API REST de facettes de recherche
Le document suivant décrit le paramètre facet de l'API de recherche ainsi que les éléments de réponse correspondant. Le paramètre facet permet d'obtenir les facettes, lesquelles sont pertinentes pour la requête de recherche. Les facettes prises en charge dans Recherche dans Portal incluent Tag, Person, Date, Source, et, pour les recherches de statut uniquement, Trend.
Format de demande
Le paramètre facet de l'API de recherche est facultatif. Quand il est absent, les facettes ne sont pas renvoyées avec les résultats de recherche. Le paramètre facet peut être répété de nombreuses fois. Chaque instance du paramètre définit un catégorie pour laquelle des facettes doivent être calculées. Par exemple: Person, Date, Tag, etc. La valeur du paramètre facet est une chaîne JSON. Un nombre d'attributs pour la chaîne JSON sont pris en charge. Tous les attributs, lesquels ont une valeur par défaut, sont facultatifs. Tout attribut inconnu est ignoré. Les attributs suivants sont pris en charge pour la chaîne JSON :
| Nom | Description | Valeur par défaut | Commentaires |
|---|---|---|---|
| id | Définit l'ID de la catégorie à partir de laquelle des facettes doivent être calculées. Cet attribut est obligatoire. | Cette valeur peut être obtenue depuis une réponse d'une demande de recherche précédente. | |
| depth | Définit le mode de collecte des valeurs de facette dans la catégorie. Si la profondeur est de 0, seule la catégorie est renvoyée. Si la profondeur est de 1, ses enfants immédiats sont également renvoyés. Si la profondeur est la valeur constante ALL, il n'y a pas de limite à la collecte des valeurs de facette. | 1 | Les valeurs négatives ne sont pas admises. |
| count | Définit le nombre maximal de valeurs à renvoyer pour cette catégorie. Si ce nombre est la valeur constante ALL, tous les descendants de la catégorie pour la profondeur fournie sont renvoyés, jusqu'au maximum. | 10 | Les valeurs négatives ne sont pas admises. La valeur maximale est de 1000. |
| sortOrder | Défini le mode de tri, qu'il soit par ordre croissant ou décroissant. Les résultats de facettes sont triés par poids. | DESC | L'attribut possède uniquement 2 valeurs autorisées : ASC, DESC. |
La structure complète du paramètre au format JSON est la suivante :
facet={"id": "<facet_id>", "depth": <depth>, "count": <count>, "sortOrder": "<order>"}Quelques exemples :
facet={"id": "Tag", "count": 50}
facet={"id": "Person", "count": 250}
facet={"id": "Date", "count": 250, "depth": 2}
facet={"id": "Source", "count": 50}
facet={"id": "Trend", "count": 50}Format de réponse
Le format de réponse est conçu pour autorisé un client de recherche par facettes, en étant aussi générique que possible. Le format est basé XML et augmente l'alimentation de recherche Atom existante par des éléments. Tous les éléments supplémentaires possèdent un espace de nom ibmsc, où ibmsc est la version courte de http://www.ibm.com/search/content/2010. L'élément racine atom:feed est augmenté avec des éléments ibmsc:facet, comme défini dans le schéma suivant :
atomFeed = element atom:feed {
ibmscFacets ~//in addition to existing elements
}
ibmscFacets = element ibmsc:facets {
attribute taxonomyId { text},
ibmscFacet*
}
ibmscFacet = element ibmsc:facet {
attribute id { text},
attribute type { text },
ibmscFacetValue*
}
ibmscFacetValue = element ibmsc:facetValue{
attribute id { text},
attribute label { text },
attribute weight { float },
ibmscFacetValue*
}Description des éléments de réponse :
| Elément | Description |
|---|---|
| ibmsc:facets | Elément racine pour toutes les informations sur les facettes. |
| ibmsc:facets/@taxonomyId | Identifie la taxonomie des facettes à utiliser dans une contrainte de catégorie. |
| ibmsc:facet | Définit la catégorie pour laquelle des facettes ont été calculées. |
| ibmsc:facet/@id | Identificateur de la catégorie. |
| ibmsc:facet/@type | Définit le type de facette. Peut être utilisé comme suggestion côté client sur la façon de rendre la facette. Pour exemple, si le type est Person, il peut être rendu en tant que lien de personne live. Si le type est Tag, il peut être rendu comme cloud. Les valeurs suivantes sont prédéfinies : Date, Tag, Person, String, Number, Integer. |
| ibmsc:facetValue | Définit une catégorie pour laquelle des résultats de recherche ont été trouvés. Un paramètre facetValue peut comporter des sous-éléments dans une structure de type arborescence. |
| ibmsc:facet:facetValue/@id | Identificateur de la catégorie pour laquelle des résultats de recherche ont été trouvés. |
| ibmsc:facetValue/@label | Libellé lisible pour cette valeur de facette. |
| ibmsc:facetValue/@weight | Nombre indiquant le poids relatif de cette valeur de facette dans les résultats de recherche. Ce nombre peut corréler le nombre réel des résultats de recherche qui correspondent à cette requête, mais cela n'est pas obligatoire. |
Remarque : Quand une valeur de facette est sélectionnée par l'utilisateur, l'API fournit les moyens suivants de répercuter cette sélection dans la demande de recherche par facettes :
- Pour limiter les résultats de recherche à ceux correspondant à cette valeur de facette, utilisez le paramètre constraint. Combinez l'id de l'élément facetValue avec l'attribut taxonomyId de l'élément facets sur la réponse pour générer la nouvelle URL de service. Cette option peut également être utilisée pour sélectionner simultanément des valeurs à deux facettes ou plus. La valeur de catégorie doit correspondre à l'Id de la valeur de facette sélectionnée.
- Pour explorer des facettes d'une sous-catégorie de la valeur de facette sélectionnée le cas échéant, utilisez l'id de l'élément facetValue comme attribut id du paramètre de demande de facette.
Exemple
<ibmsc:facets taxonomyId="facets">
<ibmsc:facet id="Date" type="Date">
<ibmsc:facetValue id="Date/2012" label="2012" weight="1">
<ibmsc:facetValue id="Date/2012/07" label="07" weight="1"/>
</ibmsc:facetValue>
</ibmsc:facet>
</ibmsc:facets>