Anmelden Erste Schritte

Benutzerdefinierte Aktivitätsprotokoll-Einträge ausgeben

Dieser Leitfaden erklärt, wie du aus deinem Plugin- oder Website-Code eigene benutzerdefinierte Einträge zum Jetpack Activity-Protokoll hinzufügen kannst.

Jetpack Activity-Protokolleinträge, die mit dieser API erstellt wurden, erscheinen neben anderen Ereignissen, etwa veröffentlichten Beiträgen oder aktualisierten Plugins. Dies ist nützlich, wenn du aussagekräftige Ereignisse für Website-Administratoren sichtbar machen möchtest, ohne eine eigene Benutzeroberfläche für ein Aktivitäts- oder Prüfprotokoll zu erstellen. Dieser Leitfaden richtet sich an Entwickler und setzt das Schreiben von benutzerdefiniertem Code voraus.

Anforderungen

  • Plugin von Jetpack in Version 15.9 oder höher oder
  • Sync-Paketversion 4.38 oder höher von Jetpack (falls dein Plugin Sync direkt benötigt).
  • Der benutzerdefinierte Beitragstyp jp_act_log_event wird automatisch registriert, sobald Sync geladen wird. Du musst ihn nicht selbst registrieren.
  • Die aufrufende Person muss über die manage_options Berechtigung verfügen (in der Regel als Website-Administrator).

So fügst du einen Eintrag zum Aktivitätsprotokoll hinzu

Du kannst benutzerdefinierte Aktivitätsprotokoll-Einträge auf drei wesentliche Arten erstellen:

  • Mit PHP über die Hilfsklasse (empfohlen).
  • Über einen REST-Client.
  • Direkt mit wp_insert_post().

Einen Eintrag mit PHP hinzufügen (empfohlen)

Verwende die Activity_Log_Event Hilfsklasse, um Einträge zu validieren und zu erstellen.

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).

  }

Bei Erfolg gibt create() die jp_act_log_event Beitrags-ID zurück.
Wenn die Validierung fehlschlägt, wird false zurückgegeben.

Die Verwendung der Hilfsklasse wird empfohlen, da sie die Validierung übernimmt und ein einheitliches Datenformat für Aktivitätsprotokoll-Einträge gewährleistet.

Einen Eintrag über einen REST-Client hinzufügen

Du kannst Einträge auch über die WordPress-REST-API erstellen.

Endpunkt

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

Anfragetext

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

Der authentifizierte Benutzer muss über die manage_options Berechtigung verfügen. Der daraus resultierende Aktivitätsprotokoll-Eintrag wird diesem Benutzer als handelnder Person zugeordnet.

Einen Eintrag hinzufügen mit wp_insert_post()

Du kannst Ereignisse auch direkt als jp_act_log_event Beiträge erstellen. Das post_content Feld sollte eine JSON-kodierte Nutzlast mit denselben Eigenschaften enthalten, die auch an anderer Stelle verwendet werden.

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',
            )
        ),
    )
);

Bei der Verwendung von wp_insert_post()bist du selbst für die Validierung dieser Werte verantwortlich. Um ungültige Einträge zu vermeiden, verwende möglichst die Activity_Log_Event Hilfsklasse.

Felddefinitionen

Jedes Ereignis im Aktivitätsprotokoll unterstützt die folgenden Eigenschaften:

  • title
    • Typ: Zeichenkette
    • Maximale Länge: 200 Zeichen
    • Nur reiner Text
    • Erforderlich
  • content
    • Typ: Zeichenkette
    • Maximale Länge: 5.000 Zeichen
    • Nur reiner Text
    • Erforderlich
  • source
    • Typ: Zeichenkette
    • Maximale Länge: 100 Zeichen
    • Kennung des auslösenden Tools (zum Beispiel my-plugin).
    • Standard: Custom entry
    • Optional
  • severity
    • Typ: Aufzählung
    • Zulässige Werte: info, success, warning, error
    • Standard: info
    • Optional

Was Website-Betreiber sehen

Benutzerdefinierte Einträge erscheinen im Aktivitätsprotokoll der Website als normale Ereignisse und werden als benutzerdefinierte Ereignisse gekennzeichnet. Im Aktivitätsprotokoll:

  • Der title wird als Überschrift des Ereignisses verwendet.
  • Der actor ist der WordPress-Benutzer, der den API-Aufruf durchgeführt hat (zum Beispiel über PHP oder REST).

Einschränkungen und Verhalten

Benutzerdefinierte Aktivitätsprotokoll-Einträge, die mit dieser API erstellt wurden, weisen folgendes Verhalten auf:

  • Nicht bearbeitbar
    Einträge können nur einmal geschrieben werden. Der benutzerdefinierte Beitragstyp mit dem Namen jp_act_log_event verweigert alle Berechtigungen für edit_* und delete_*.
  • Nicht automatisch über Publicize geteilt
    Einträge werden nicht über Jetpack Social geteilt, selbst wenn ein Plugin eines Drittanbieters Unterstützung für Publicize für den benutzerdefinierten Beitragstyp hinzufügt.
  • Nicht in Sitemaps enthalten
    Der jp_act_log_event Beitragstyp ist ausdrücklich von den Jetpack-Sitemaps ausgeschlossen.
  • Im Frontend privat
    Der Beitragstyp verwendet:
    • public => false
    • publicly_queryable => false
    • exclude_from_search => true
    Dies hält Einträge aus Frontend-Abfragen und der Suche heraus, ermöglicht dem Aktivitätsprotokoll jedoch weiterhin, auf sie zuzugreifen und sie anzuzeigen.

Was this article helpful?