External Entities

External Entities est une famille en couches de modules Drupal pour les sites dont le contenu réside en partie ailleurs. Les enregistrements issus d’une API externe ou d’un jeu de données deviennent des entités Drupal avec des champs, des modes d’affichage et Gérer l’affichage, de sorte que les pages peuvent les afficher, les référencer et les lister comme n’importe quel autre contenu, tandis que les données restent connectées à leur source.

Un substrat partagé gère ce dont chaque intégration a besoin : HTTP mis en cache, une seule requête par source, quel que soit le nombre de parties d’une page qui la demandent, et une mise en miroir champ par champ. Une nouvelle source de données est donc un petit module qui se branche sur le framework, et non une nouvelle intégration. Species External Entity et Editorial Intelligence sont construits de cette manière, et le catalogue Research Library repose dessus.

Substrat

entities_ext, construit sur le moteur du module contribué External Entities ; request_bus, la couche d'appels sortants ; dynamic_mirror_base, la mise en miroir par champ

Types génériques

entity_ext : un type d'entité externe adossé à une API HTTP, défini dans la configuration au lieu d'un plugin de stockage personnalisé

Modules sources

Un par source externe ou jeu de données, parmi lesquels wikipedia_ext, data_ext, scripture_x, books_ext, scholar_ext, places_ext, artworks_ext, iiif_x, wikidata_x et authority_x

Drupal core

10 ou 11

Nécessite

key ; entities_ext nécessite également request_bus, qui lui-même ne nécessite que Drupal core et key

État

Construit et en développement actif, aucune version 1.0 (modules en 0.1.0-dev). Le substrat tourne en production sur Biodiversa, Museo Avellonia et le Quercus Project ; la plupart des modules sources sont en développement sur la plateforme de recherche propre à MADDev.

Types d'entités externes

entities_ext ne définit aucun type de contenu propre. Chaque module consommateur enregistre ses types d'entités externes sur le substrat partagé, par exemple wikipedia_page, species_x ou editorial_news. Le sous-module xntt_views liste les entités externes dans Views, xnttsql lit les schémas SQL externes, et entities_ext_mng surveille chaque source pour détecter les points de terminaison manquants ou les champs modifiés et protège le rendu lorsqu'une source est indisponible.

Miroir par champ

dynamic_mirror_base décide, champ par champ, d'où vient une valeur : en direct depuis la source, une copie mise en miroir, ou une valeur locale conservée définitivement. Un éditeur peut verrouiller n'importe quel champ sur une valeur locale qui survit à chaque actualisation depuis l'amont. dmb_ui offre aux éditeurs des actions de verrouillage, modification, resynchronisation et déverrouillage, et dmb_harvest actualise les valeurs mises en miroir selon un calendrier.

Faits isolés

data_ext résout un fait externe unique, comme une légende, un prix ou une coordonnée, sans mettre en miroir un enregistrement complet. Il est livré avec les intitulés de la Classification de la Bibliothèque du Congrès et de la Classification décimale universelle.

Types de plugins

• @StorageClient et @ExternalSource : un plugin par API amont, essayés par ordre de poids jusqu'à ce que l'un d'eux réponde
• plugins de mappage de champs, de mappage de propriétés, de traitement de données et d'agrégation de données pour transformer les données d'une source en champs
• @DmbAdapter : relie un type d'entité à la mise en miroir par champ
• plugins de source par module, tels que @WikipediaSource, @ScriptureSource, @ScholarSource, @ArtworkSource et @DatumSource

Services

request_bus.bus (également disponible sous entities_ext.request_bus), data_ext.resolver, wikidata_x.client, authority_x.resolver, scholar_ext.resolver, iiif_x.manifest_loader.

Administration

• /admin/config/services/dmb/policy : politique de mise en miroir par champ
• /admin/content/dmb-overrides : toutes les surcharges locales
• /admin/config/services/dmb/harvest : le calendrier d'actualisation
• /admin/config/services/wikipedia-ext : paramètres de Wikipédia

Atelier du développeur

entities_ext_builder, en développement, construit des types d'entités externes sans configuration écrite à la main : il sonde un point de terminaison en direct, prévisualise la manière dont les champs seront extraits avant tout enregistrement, et peut recourir à un fournisseur d'IA pour trouver la documentation d'une API. Il ne contient aucune logique d'exécution, donc sa désinstallation laisse fonctionner chaque type d'entité externe qu'il a construit.

• Encyclopédique : Wikipedia et tout site MediaWiki (wikipedia_ext) ; Wikidata (wikidata_x)
• Livres et recherche : Open Library et Google Books, réconciliés par ISBN (books_ext) ; OpenAlex, Crossref, arXiv, PubMed et Semantic Scholar (scholar_ext)
• Noms : identifiants VIAF, ORCID, ULAN, Wikidata et ISNI réconciliés en une personne ou une organisation (authority_x)
• Lieux : Pleiades et le World Historical Gazetteer (places_ext)
• Collections : le Metropolitan Museum of Art, l'Art Institute of Chicago et le Cleveland Museum of Art, aucun ne nécessitant de clé (artworks_ext) ; les manifestes d'images IIIF, versions 2 et 3 (iiif_x)
• Textes : sources et traductions d'Écritures en hébreu, grec et copte (scripture_x)
• Légendes de classification : id.loc.gov et le résumé de la CDU (data_ext)

Chaque appel sortant passe par request_bus, qui met en cache et combine les requêtes ; les sources qui nécessitent une clé la conservent dans le module key, et non dans le code. Lorsque le contenu provient d'une source externe, copyrights_ext écrit sa licence et son crédit dans le champ de copyright du site lors de son importation ou de sa mise en miroir, ce que Copyrights Guard fait ensuite respecter.

• Enregistrez un besoin, n’émettez pas de requête. Les appelants indiquent au bus de requêtes ce dont ils ont besoin ; il fusionne les requêtes identiques, combine les champs demandés par différentes parties d’une page, regroupe par source et mémorise la réponse, y compris « aucune donnée », pour le reste de la requête. Une page avec dix sections reposant sur Wikipédia n’effectue qu’un seul appel à Wikipédia.
• Une source morte ne casse jamais une page. Une source indisponible, lente ou malformée ne renvoie rien au lieu de lever une exception, et la page s’affiche sans elle.
• Uniquement les champs demandés par une page. Le chargement d’une entité externe résout les champs réellement demandés, et non l’enregistrement externe complet.
• Trois paramètres par champ, et non un seul mode. L’origine d’une valeur (en direct, miroir ou local), ce qui se passe lorsque la source l’abandonne (supprimer ou conserver), et l’endroit où la valeur est stockée sont définis indépendamment ; le verrou d’un éditeur prévaut sur les trois.
• Dépendances souples. Les modules dépendent strictement uniquement du substrat et de key ; toute autre intégration est vérifiée à l’exécution, de sorte que la famille continue de fonctionner lorsqu’un module est absent.
• Des noms qui disent ce qu’est un module. _ext marque un module source, _x un module qui étend le framework, et l’absence de suffixe un utilitaire sans dépendance à celui-ci.