Se connecter Commencer

Émettre des entrées personnalisées dans le journal d’activité

Ce guide explique comment ajouter vos propres entrées personnalisées au journal Jetpack Activity depuis le code de votre extension ou de votre site.

Les entrées du journal Jetpack Activity créées avec cette API apparaissent à côté d’autres événements, comme la publication d’articles ou la mise à jour d’extensions. Cette fonctionnalité est utile si vous souhaitez présenter des événements importants aux administrateurs du site sans créer votre propre interface de journal d’activité ou d’audit. Ce guide destiné aux développeurs implique l’écriture de code personnalisé.

Prérequis

  • Extension Jetpack en version 15.9 ou ultérieure, ou
  • Package Sync de Jetpack en version 4.38 ou ultérieure (si votre extension nécessite directement Sync).
  • Le type de publication personnalisé jp_act_log_event est enregistré automatiquement au chargement de Sync. Vous n’avez pas besoin de l’enregistrer vous-même.
  • L’appelant doit disposer de l’autorisation manage_options (généralement un administrateur du site).

Comment ajouter une entrée au journal d’activité

Vous pouvez créer des entrées personnalisées dans le journal d’activité de trois façons principales :

  • Depuis PHP à l’aide de la classe utilitaire (recommandé).
  • Depuis un client REST.
  • Directement à l’aide de wp_insert_post().

Ajouter une entrée depuis PHP (recommandé)

Utilisez la classe utilitaire Activity_Log_Event pour valider et créer des entrées.

use Automattic\Jetpack\Sync\Activity_Log_Event;

  $post_id = Activity_Log_Event::create( array(
      'title'    => 'Membership sync failed',
      'content'  => 'Remote API returned 401. Retry queued.',
      'source'   => 'my-plugin',
      'severity' => 'error',
  ) );

  if ( false === $post_id ) {

      // Validation failed (missing/invalid title or content, bad severity).

  }

En cas de réussite, create() renvoie l’identifiant de publication jp_act_log_event.
En cas d’échec de la validation, elle renvoie false.

L’utilisation de la classe utilitaire est recommandée, car elle gère la validation et garantit un format de données cohérent pour les entrées du journal d’activité.

Ajouter une entrée depuis un client REST

Vous pouvez également créer des entrées à l’aide de l’API REST de WordPress.

Point d’accès

POST /wp-json/wp/v2/activity-log-events
Content-Type: application/json
Authorization: OAuth token with admin scope

Corps de la requête

{
  "title": "Membership sync failed",
  "content": "Remote API returned 401. Retry queued.",
  "source": "my-plugin",
  "severity": "error"
}

L’utilisateur authentifié doit disposer de l’autorisation manage_options. L’entrée résultante du journal d’activité sera attribuée à cet utilisateur en tant qu’auteur de l’action.

Ajouter une entrée à l’aide de wp_insert_post()

Vous pouvez également créer directement des événements en tant que publications de type jp_act_log_event. Le champ nommé post_content doit contenir une charge utile encodée au format JSON avec les mêmes propriétés que celles utilisées ailleurs.

wp_insert_post(
    array(
        'post_type'   => 'jp_act_log_event',
        'post_status' => 'publish',
        'post_title'  => 'Cache flushed',
        'post_content'=> wp_json_encode(
            array(
                'title'    => 'Cache flushed',
                'content'  => 'Manual cache flush during incident response.',
                'source'   => 'my-snippet',
                'severity' => 'info',
            )
        ),
    )
);

Lorsque vous utilisez wp_insert_post(), vous devez valider vous-même ces valeurs. Pour éviter les entrées non valides, privilégiez la classe utilitaire Activity_Log_Event chaque fois que possible.

Définition des champs

Chaque événement du journal d’activité accepte les propriétés suivantes :

  • title
    • Type : chaîne
    • Longueur maximale : 200 caractères
    • Texte brut uniquement
    • Obligatoire
  • content
    • Type : chaîne
    • Longueur maximale : 5 000 caractères
    • Texte brut uniquement
    • Obligatoire
  • source
    • Type : chaîne
    • Longueur maximale : 100 caractères
    • Identifiant de l’outil à l’origine de l’action (par exemple, my-plugin).
    • Valeur par défaut : Custom entry
    • Facultatif
  • severity
    • Type : énumération
    • Valeurs autorisées : info, success, warning, error
    • Valeur par défaut : info
    • Facultatif

Ce que voient les propriétaires de sites

Les entrées personnalisées apparaissent dans le journal d’activité du site comme des événements classiques, identifiés comme des événements personnalisés. Dans le journal d’activité :

  • Le titre est utilisé comme titre de l’événement.
  • L’acteur est l’utilisateur WordPress qui a effectué l’appel à l’API (par exemple via PHP ou REST).

Limitations et comportement

Les entrées personnalisées du journal d’activité créées avec cette API ont le comportement suivant :

  • Non modifiables
    Les entrées ne peuvent être écrites qu’une seule fois. Le type de publication personnalisé jp_act_log_event n’autorise ni edit_* ni delete_*.
  • Non publiées automatiquement
    Les entrées ne seront pas partagées via Jetpack Social, même si une extension tierce ajoute la prise en charge de Publicize pour le type de publication personnalisé.
  • Non inclus dans les sitemaps
    Le type de publication nommé jp_act_log_event est explicitement exclu des sitemaps de Jetpack.
  • Privées sur le front-end
    Le type de publication utilise :
    • public => false
    • publicly_queryable => false
    • exclude_from_search => true
    Cela exclut les entrées des requêtes et des recherches sur le front-end, tout en permettant au journal d’activité d’y accéder et de les afficher.

Was this article helpful?