Importer du contenu dans Drupal via un webservice sécurisé avec OAuth2

Prérequis

Pour comprendre et mettre en place la solution dans cet article, vous devez savoir installer des modules (nous aurons besoin de Migrate et Migrate Plus), créer votre propre module, notamment pour implémenter des "migrations", et savoir utiliser Drush, l'outil de gestion de Drupal en ligne de commande.

Connaissez-vous le module Migrate ? 

C'est un module appartenant au cœur de Drupal qui permet à l'origine de migrer d'une ancienne version de Drupal 6 ou 7 vers la version courante. Mais désormais il fait bien plus. Il permet de migrer des données de toutes autres plateformes vers Drupal, c'est à dire créer des entités dans Drupal à partir de fichiers plats (txt, csv, json, xml) ou en se branchant sur des bases de données ou API externes...

Toute la magie réside dans l'écriture d'un simple fichier YAML, un document texte qui permet de décrire une configuration logicielle de façon lisible et facilement intelligible pour l'humain.

Dans le cadre de Migrate, on va utiliser le fichier YAML pour décrire la source des données et la destination dans Drupal. Cette entité de configuration que l'on va décrire en YAML s'appelle une migration. 

Il y a beaucoup d'options existantes dans l'écosystème Migrate (module du coeur + modules contribués comme Migrate Tools, Migrate Plus, Migrate Source CSV, etc) et si vous avez des cas particuliers, il suffit de prendre un plugin proche de ce que vous voulez faire comme modèle et de le surcharger ou le dupliquer pour en faire un nouveau adapté à vos besoins.

Astuce : dans l'écosystème Migrate, la meilleure documentation se trouve souvent dans le commentaire d'entête des plugins. Vous y trouverez notamment des exemples de configuration YAML.

Le cas de l'API sécurisée avec Oauth2

Je ne l'ai pas découvert facilement, d'où ma volonté d'en faire un article de blog, mais il existe un plugin de connexion Oauth2 dans le module Migrate Plus.

Le principe est d'ajouter une sous-section authentication dans la section source pour décrire la technique d'authentification et les identifiants... le module Migrate Plus s'occupe du reste.

source:
  plugin: url
  data_fetcher_plugin: http
  data_parser_plugin: json
  authentication:
    plugin: oauth2
    base_uri: http://api.example.com
    token_url: /oauth/v2/token
    grant_type: client_credentials
    client_id: '' # Set this var in your settings.local.php
    client_secret: '' # Set this var in your settings.local.php
  urls: http://api.example.com/api/entity?option=2

Par sécurité, il est recommandé de ne pas stocker vos identifiants et mots de passe dans ce fichier de configuration. L'idéal est de les écrire dans le fichier settings.local.php. Pour notre exemple, on y ajoutera donc les 2 lignes suivantes :

$config['migrate_plus.migration_group.example_entity']['source']['authentication']['client_id'] = 'YourAuthenticationId';
$config['migrate_plus.migration_group.example_entity']['source']['authentication']['client_secret'] = 'YourAuthenticationPassword';

Exemple complet de configuration YAML avec connexion Oauth2

Voici un exemple complet de fichier YAML de migration pour avoir un peu de contexte autour de l'intégration de l'authentification.

Par convention, on placera ce fichier dans un module custom :

example_module/config/install/migrate_plus.migration.example_entity.yml

langcode: fr
status: true
id: example_entity
label: Example entity
migration_group: example_api
migration_tags:
  - example_api
source:
  plugin: url
  data_fetcher_plugin: http
  data_parser_plugin: json
  authentication:
    plugin: oauth2
    base_uri: http://api.example.com
    token_url: /oauth/v2/token
    grant_type: client_credentials
    client_id: '' # Set this var in your settings.local.php
    client_secret: '' # Set this var in your settings.local.php
  urls: http://api.example.com/api/entity?option=2
  item_selector: 0
  fields:
    -
      name: name
      label: 'Name'
      selector: name
    -
      name: id
      label: 'ID'
      selector: id
    -
      name: created_at
      label: 'Created at'
      selector: created_at
    -
      name: updated_at
      label: 'Updated at'
      selector: updated_at
    # [...some other source fields...]
  ids:
    id:
      type: integer
process:
  title: name
  field_remote_id: id
  created:
    plugin: format_date
    source: created_at
    from_format: 'Y-m-d\TH:i:sP'
    to_format: 'U'
    from_timezone: 'UTC'
    to_timezone: 'UTC'
  changed:
    plugin: format_date
    source: updated_at
    from_format: 'Y-m-d\TH:i:sP'
    to_format: 'U'
    from_timezone: 'UTC'
    to_timezone: 'UTC'
  # [...some other destination fields...]
destination:
  plugin: 'entity:node'
  default_bundle: my_entity

Pour installer et exécuter cette migration avec Drush

Et enfin, pour tester cette migration, il faut d'abord l'installer dans notre site Drupal. Pour cela, on peut utiliser Drush qui permet d'importer des fichiers de configuration à partir d'un dossier en particulier :

drush cim -y --partial --source=modules/custom/example_module/config/install

Il nous reste à exécuter cette migration, avec Drush ça donne :

drush migrate:import example_entity

Si tout va bien vous devriez voir quelque chose comme ça dans votre terminal :

Processed 0 items (123 created, 0 updated, 0 failed, 0 ignored) - done with 'example_entity'

Je pense qu'il est possible de faire ces mêmes opérations via l'interface d'administration si vous préférez... à vous de jouer ;-)