Points d’extrémité du paquet/de l’ensemble de données

Documentation API

Points d’extrémité du paquet/de l’ensemble de données

  1. Accès/Liste de tous les ensembles de données du registre de l’IITA
  2. Rechercher des ensembles de données de l’IITA et accéder aux métadonnées des ensembles de données
  3. Accéder aux métadonnées des ensembles de données et à leurs ressources
  4. Créer un ensemble de données
  5. Mettre à jour un ensemble de données
  6. Corriger un ensemble de données
  7. Supprimer un ensemble de données


1. Accès/Liste de tous les ensembles de données du registre de l’IITA

Fournit la liste des noms des ensembles de données du registre de l’IITA (paquets). Par défaut, le nombre d’articles fournis est fixé à 1 200. Lorsque l’en-tête d’autorisation est fourni, le système renvoie tous les ensembles de données privées auxquels l’utilisateur a accès.

Point d’extrémité : /package_list

Méthode : GET

Autorisation : facultatif.

Paramètres :

  • limit (int) (facultatif) – si une limite est fixée, la liste des ensembles de données sera divisée en pages dont le nombre ne peut dépasser la limit établie par page, et une seule page est fournie à la fois.
  • offset (int) (facultatif) – lorsqu’une limite est donnée, le décalage à partir duquel le paquet est fourni.

Exemples :


2. Rechercher des ensembles de données de l’IITA et accéder aux métadonnées des ensembles de données

Recherches de paquets satisfaisant à un critère de recherche donné. Cette action accepte les paramètres de requête de recherche Solr (voir les détails ci-après) et renvoie un dictionnaire de résultats, y compris des ensembles de données à la taille du dictionnaire correspondant aux critères de recherche, un compte de recherche, ainsi que des renseignements sur les facettes.

Point d’extrémité : /package_search

Méthode : GET

Autorisation : pas nécessaire.

Paramètres Solr : veuillez lire la documentation sur les paramètres Solr.

Paramètres :

  • q (chaîne de caractères) (facultatif) – la requête Solr. Par défaut : "*:*"
  • fq (chaîne de caractères) (facultatif) – toutes les requêtes de filtre à appliquer. Veuillez consulter les exemples ci-après.
  • fq_list (chaîne de caractères) (facultatif) – requêtes de filtre supplémentaires à appliquer.
  • sort (chaîne de caractères) (facultatif) – trie les résultats de recherche. Par défaut : « score desc, metadata_modified desc ». Conformément aux documents sur les paramètres Solr, il s'agit d'une chaîne de noms de champs et d'ordres de tri séparés par des virgules.
  • rows (int) (facultatif) – le nombre maximum de lignes correspondantes (ensembles de données) à renvoyer. Par défaut : 10, limite maximale : 1 000
  • start (int) (facultatif) – le décalage dans le résultat complet quant à l'endroit où l'ensemble de données renvoyé doit commencer.
  • facet (chaîne de caractères) (facultatif) – définit l’activation des résultats à facettes. Par défaut : True
  • facet.mincount (int) (facultatif) – les nombres minimums de champs de facettes devant être inclus dans les résultats.
  • facet.limit (int) (facultatif) – le nombre maximal de valeurs renvoyées par les champs de facettes. Une valeur négative signifie « illimité ». On peut la définir à l'échelle de l'instance avec l'option de configuration « search.facets.limit ». La valeur par défaut est fixée à 50.
  • facet.field (chaîne de caractères) (facultatif) – les champs à facettes. Par défaut vide. Si vide, le champ ne contient aucun renseignement sur les facettes.
  • include_drafts (bool) (facultatif) – si la valeur est « True », les ébauches d’ensembles de données seront incluses dans les résultats. L’utilisateur ne recevra que ses propres ébauches d’ensembles de données. Remarque : l’autorisation avec clé API requise dans ce cas doit être « true ».
  • include_private (bool) (facultatif) – si la valeur est « True », les ensembles de données privés seront inclus dans les résultats. Seuls les ensembles de données privés provenant des organisations de l'utilisateur seront renvoyés. Remarque : l’autorisation avec clé API requise dans ce cas doit être « true ».

Exemples :


3. Accéder aux métadonnées des ensembles de données et à leurs ressources

Renvoyer les métadonnées d’un ensemble de données (paquet) et ses ressources

Point d’extrémité : /package_show

Méthode : GET

Autorisation : pas nécessaire.

Paramètres :

  • id (chaîne de caractères) (obligatoire) – l’identifiant ou le nom de l’ensemble de données.
  • use_default_schema (bool) (facultatif) – utilisation du schéma de paquet par défaut au lieu d'un schéma personnalisé défini avec un module d'extension « IDatasetForm ». Par défaut : valeur « False »
  • include_tracking (bool) (facultatif) – ajoute des informations de suivi à l’ensemble de données et aux ressources. Par défaut : Faux.

Exemples :


4. Créer un ensemble de données

Créer un nouvel ensemble de données (paquet). Vous devez avoir l’autorisation de créer de nouveaux ensembles de données. Pour indiquer des signataires dans le nouvel ensemble de données, vous devez également être autorisé à modifier ces signataires.

Point d’extrémité : /package_create

Méthode : POST

Autorisation : obligatoire.

Autres en-têtes de la requête : ('Content-Type', 'application/json; charset=utf-8')

Paramètres :

  • name (chaîne de caractères) (obligatoire) – le nom du nouvel ensemble de données, une chaîne comprenant entre 2 et 100 caractères, contenant uniquement des caractères alphanumériques en minuscule, - et _, p. ex., « warandpeace »
  • title (chaîne de caractères) (obligatoire) – le titre de l’ensemble de données. Par défaut : le même que celui du name
  • private (bool) (obligatoire) – si la valeur est « True », un ensemble de données privés est créé.
  • filetype (chaîne de caractères) (obligatoire) – le type de fichier doit être soit « activity », soit « organization ».
  • owner_org (chaîne de caractères) (obligatoire) – l’identifiant de l’organisation propriétaire de l’ensemble de données, voir organization_list() pour prendre connaissance des valeurs disponibles. Ce paramètre devient facultatif lorsque l’option de configuration « ckan.auth.create_unowned_dataset » est définie sur la valeur « True ».
  • author (chaîne de caractères) (facultatif) – le nom de l’auteur de l’ensemble de données.
  • author_email (chaîne de caractères) (facultatif) – l’adresse électronique de l’auteur de l’ensemble de données.
  • maintainer (chaîne de caractères) (facultatif) – le nom de la personne qui assure la maintenance de l’ensemble de données.
  • maintainer_email (chaîne de caractères) (facultatif)– l’adresse électronique de la personne qui assure la maintenance de l’ensemble de données.
  • notes (chaîne de caractères) (facultatif) – une description de l’ensemble de données.
  • url (chaîne de caractères) (facultatif) – le lien URL de la source de l’ensemble de données.
  • resources (liste des dictionnaires de ressources) – les ressources de l’ensemble de données, voir « resource_create() » pour en savoir plus sur les formats des dictionnaires de ressources (facultatif). Un ensemble de données de l’IITA ne peut avoir qu’une seule ressource.
  • extras (liste des dictionnaires supplémentaires de l’ensemble de données) (facultatif) – les fonctions supplémentaires de l’ensemble de données (facultatif) ; ces fonctions supplémentaires sont des éléments de métadonnées arbitraires (clé : valeur) qu’il est possible d’ajouter aux ensembles de données ; chaque dictionnaire supplémentaire doit disposer de clés 'key' (une chaîne de caractères), 'value' (une chaîne de caractères).
  • secondar_publisher (chaîne de caractères) (facultatif) – l’ensemble de données est publié au nom du signataire.
  • country (chaîne de caractères) (facultatif) – le code du pays bénéficiaire.
  • tags (liste des dictionnaires de mots-clés) (facultatif)– les mots-clés de l’ensemble de données, voir « tag_create() » pour en savoir plus sur les formats des dictionnaires de mots-clés.
  • iati_version (chaîne de caractères) (facultatif) – la version de la norme de l’IITA.
  • activity_count (chaîne de caractères) (facultatif) – le décompte du nombre d’activités déclarées.
  • language (chaîne de caractères) (facultatif) – le code ISO 639-1 de la langue par défaut du fichier (p. ex., « en »).

Exemples :

  • Cas 1 : Créer un ensemble de données sur les activités avec le signataire « my-test-publisher-3 ».

Point d’extrémité : https://iatiregistry.org/api/action/package_create

headers = {"Content-Type": "application/json; charset=utf-8", "Authorization":”XXX”}

payload = { "name": "my-test-publisher-3-activity", "title": "My test package", "private": False, "filetype": "activity",

"owner_org": "71a7698a-b14f-43c2-b113-b8eb884da7af", "resources": [ { "url": "https://aidstream.s3.us-west-2.amazonaws.com/xml/acfspain-ge.xml", "format":"IATI-XML", } ] }

  • Cas 2 : Créer un ensemble de données sur l’organisation avec le signataire « my-test-publisher-3 » et le code de pays « ie ».

Point d’extrémité : https://iatiregistry.org/api/action/package_create

headers = {"Content-Type": "application/json; charset=utf-8", "Authorization":”XXX”}

payload = { "name": "my-test-publisher-3-org", "title": "My test package org", "private": False, "filetype": "organisation",

"owner_org": "71a7698a-b14f-43c2-b113-b8eb884da7af", "country": "ie", "resources": [ { "url": "https://aidstream.s3.us-west-2.amazonaws.com/xml/acfspain-ge.xml", "format":"IATI-XML", } ] }


5. Mettre à jour un ensemble de données

Mettre à jour un ensemble de données (paquet). Vous devez être autorisé à modifier l’ensemble de données et les groupes s’y rattachant. Il est recommandé de lancer la requête « package_show() », d’apporter les modifications souhaitées aux résultats obtenus et d’effectuer la requête « package_update() ».

La différence entre les méthodes de mise à jour et de correction est que la correction mettra à jour les paramètres précisés sans modifier les autres paramètres, tandis que la mise à jour supprimera tous les paramètres qui ne sont pas explicitement fournis dans le dictionnaire de données (data_dict.).

Point d’extrémité : /package_update

Méthode : POST

Autorisation : obligatoire.

Autres en-têtes de la requête : ('Content-Type', 'application/json; charset=utf-8')

Paramètres :

  • id (chaîne de caractères) (obligatoire) – l’identifiant de l’ensemble de données.
  • Pour plus de paramètres, voir package_create().

Exemples :

  • Cas 1 : Mettons à jour l’ensemble de données « my-test-publisher-3-org » pour qu’il passe de « My test package org » à « My test new title org ». Remarque : il est recommandé d’utiliser « package_update » ainsi que « package_show ».

Point d’extrémité : https://iatiregistry.org/api/action/package_update

headers = {"Content-Type": "application/json; charset=utf-8", "Authorization":”XXX”}

payload = {'license_title': 'Open Data Commons Attribution Licence', 'maintainer': None, 'relationships_as_object': [], 'private': False, 'maintainer_email': None, 'num_tags': 0, 'id': '4008f48f-b9e1-4c2e-8e47-3928bf66a056', 'metadata_created': '2021-01-19T23:25:07.399494', 'metadata_modified': '2021-01-19T23:25:09.999163', 'author': None, 'author_email': None, 'state': 'active', 'version': None, 'creator_user_id': 'a6f09bb2-88d2-4219-80a2-9b606bdf4ac3', 'type': 'dataset', 'resources': [{'mimetype': '', 'cache_url': None, 'hash': '9148c7e5645290213a13897583d1c5c40c9798e6', 'description': None, 'metadata_modified': '2021-01-19T23:25:10.010376', 'cache_last_updated': None, 'url': 'https://aidstream.s3.us-west-2.amazonaws.com/xml/acfspain-ge.xml', 'name': None, 'format': 'IATI-XML', 'package_id': '4008f48f-b9e1-4c2e-8e47-3928bf66a056', 'created': '2021-01-19T23:25:07.402246', 'state': 'active', 'mimetype_inner': None, 'last_modified': None, 'position': 0, 'url_type': None, 'id': 'c13afd1f-91d6-4ee6-921b-4ec405b0a774', 'resource_type': None, 'size': 4417}], 'num_resources': 1, 'tags': [], 'groups': [], 'license_id': 'odc-by', 'relationships_as_subject': [], 'organization': {'description': '', 'created': '2021-01-19T22:50:46.969280', 'title': 'My Test Publisher 3', 'name': 'my-test-publisher-3', 'is_organization': True, 'state': 'active', 'image_url': '', 'type': 'organization', 'id': '71a7698a-b14f-43c2-b113-b8eb884da7af', 'approval_status': 'approved'}, 'name': 'my-test-publisher-3-org', 'isopen': True, 'url': None, 'notes': None, 'owner_org': '71a7698a-b14f-43c2-b113-b8eb884da7af', 'license_url': 'http://www.opendefinition.org/licenses/odc-by', 'title': 'My test new title org'}


6. Corriger un ensemble de données

Vous êtes en mesure de créer ou de mettre à jour partiellement des ressources avec « package_patch ». Si vous procédez à la mise à jour de ressources existantes, assurez-vous d’indiquer l’identifiant de la ressource. Les ressources existantes exclues de « package_patch data_dict » seront supprimées. Les ressources figurant dans « package data_dict » sans identifiant seront traitées comme de nouvelles ressources et ajoutées. Les nouvelles ressources ajoutées à l’aide de la méthode de correction ne créent pas de visualisations par défaut. Vous devez être autorisé à modifier l’ensemble de données et les groupes s’y rattachant.

La différence entre les méthodes de mise à jour et de correction est que la correction mettra à jour les paramètres précisés sans modifier les autres paramètres, tandis que la mise à jour supprimera tous les paramètres qui ne sont pas explicitement fournis dans le dictionnaire de données (data_dict.).

Point d’extrémité : /package_patch

Méthode : POST

Autorisation : obligatoire.

Autres en-têtes de la requête : ('Content-Type', 'application/json; charset=utf-8')

Paramètres :

  • id (chaîne de caractères) (obligatoire) – l’identifiant de l’ensemble de données.
  • Pour plus de paramètres, voir package_create().

Exemples :

  • Cas 1 : Corrigeons le titre de l’ensemble de données « my-test-publisher-3-org ». Remplaçons donc « My test new title org » par « My test patch title ».

Point d’extrémité : https://iatiregistry.org/api/action/organization_patch

headers = {"Content-Type": "application/json; charset=utf-8", "Authorization":”XXX”}

payload ={'id': '4008f48f-b9e1-4c2e-8e47-3928bf66a056', 'title': 'My test patch title'}


7. Supprimer un ensemble de données

Supprimer des ensembles de données. Cette option permet de supprimer un ensemble de données du Web et des visualisations de l’API, à l’exception de la corbeille. Vous devez avoir l’autorisation de supprimer l’ensemble de données.

Point d’extrémité : /package_delete

Méthode : POST

Autorisation : obligatoire.

Autres en-têtes de la requête : ('Content-Type', 'application/json; charset=utf-8')

Paramètres :

  • id (chaîne de caractères) (obligatoire) – l’identifiant de l’ensemble de données.

Exemples :

  • Cas 1 : Supprimons l’ensemble de données « my-test-publisher-3-activity ».

Point d’extrémité : https://iatiregistry.org/api/action/package_delete

headers = {"Content-Type": "application/json; charset=utf-8", "Authorization":”XXX”}

payload = {'id': 'e6471512-d3e9-4999-a692-82ae1893e346'}