Aktivitätsprotokoll-API

NordPass Enterprise bietet jetzt eine Aktivitätsprotokoll-API-Integration, mit der Sie den Zugriff von Mitgliedern verwalten und Aktivitäten in Ihrer Organisation überwachen können. Nachfolgend finden Sie eine Anleitung, wie Eigentümer und Admins Aktivitätsprotokolle über die API anzeigen können.

Hinweis: Bevor Sie fortfahren, vergewissern Sie sich, dass die Kontoberechtigungen eingerichtet sind, indem Sie der Anleitung zur NordPass-Token-Verwaltung folgen.

API-Einrichtung

Die URLs der Aktivitätsprotokoll-API sind rechenzentrumsspezifisch – Ihre Organisation muss die entsprechende URL für das Rechenzentrum verwenden, in dem sich Ihr Konto befindet.

• EU: https://api-activities.eu.nordpass.com/activities/query 
• USA: https://api-activities.us.nordpass.com/activities/query 

Anforderungs-Header

Wenn Sie eine POST-Anforderung an die Aktivitätsprotokoll-API senden, stellen Sie sicher, dass Sie beide der folgenden Header einschließen:

• Autorisierung – Die POST-Anforderung an eine Aktivitätsprotokoll-API muss mithilfe des in der Business-Verwaltungsoberfläche generierten Tokens autorisiert werden. 
• Content-Type – Beim Initiieren einer POST-Anforderung ist es wichtig, einen Content-Type-Header anzugeben, um den Medientyp der im Anforderungstext übertragenen Daten explizit anzugeben.
  Für die Aktivitätsprotokoll-API müssen Sie den Content-Type auf application/json setzen, da die Anforderung im JSON-Format übertragen wird.

Beispiel:

Autorisierung: GENERATED_ACTIVE_TOKEN
			Content-Type: application/json

Filterung und Paginierung

• Diese API ermöglicht das Filtern nach timestamp_from und timestamp_to. Wenn der optionale Filter nicht angegeben wird, werden die Informationen für die letzten 7 vollen Tage zurückgegeben. Der für die Filterung angegebene Zeitraum darf maximal 90 Tage umfassen.

• user_uuids ist ein optionaler Filter. Wenn er nicht angegeben wird, werden Informationen für alle Nutzer basierend auf anderen Filterkriterien zurückgegeben. Dieser Filter akzeptiert ein Array von String-Werten, sodass bis zu 500 User-UUID-Werte in einer einzigen Filteranforderung enthalten sein können:

  1. Melden Sie sich als Eigentümer oder Admin in der Verwaltungsoberfläche an.

  2. Öffnen Sie den Entwickler-Modus.

  3. Navigieren Sie im linken Seitenmenü zum Mitgliederbereich.

  4. Öffnen Sie im Entwickler-Modus die Registerkarte „Networks“ und suchen Sie nach v1/ecp/users.

  5. Der Header sollte eine GET-Anforderung anzeigen.

  6. Erfassen Sie die UUIDs aller aktiven Nutzer aus der Registerkarte „Response“.
     
     Hinweis: Um die UUIDs von gesperrten und gelöschten Nutzern zu erhalten, sind die gleichen Schritte durchzuführen.
      

• Sie können auch die Suchfunktion nach item_id verwenden. So können Sie bestimmte Aktivitätsprotokolle schneller finden, da Sie nur die 36-stellige UUID des Elements benötigen.

• Außerdem können Sie die Anzahl der zurückgegebenen Datensätze mithilfe der Filteroption per_page verwalten, die einen Bereich von 1 bis 100 Datensätzen pro Anforderung zulässt. Wenn die Option per_page nicht angegeben wird, gilt standardmäßig eine Anzahl von 30 Datensätzen pro Seite.

• Mit der Filteroption page können Sie Ergebnisse für eine bestimmte Seite anfordern. Die Seitenzahl muss mindestens 1 sein und darf die Gesamtzahl der verfügbaren Seiten nicht überschreiten. Wenn die Option page nicht angegeben ist, gibt die API standardmäßig die erste Seite zurück.

Beispiel:

{
			  "timestamp_from": TIMESTAMP_FILTER_FROM,
			  "timestamp_to": TIMESTAMP_FILTER_TO,
			  "user_uuids": ["USER_UUID"],
			  "item_id": "ITEM_UUID",
			  "per_page": 30,
			  "page": 1
			}

Vollständiger Datenabruf

Um eine vollständige Aufzeichnung ohne Lücken zu gewährleisten, empfehlen wir unseren Datenaufbewahrungsansatz, bei dem während Unterbrechungen generierte Ereignisse aufbewahrt und synchronisiert werden, sobald der Dienst wiederhergestellt ist. Ihre Implementierung ist dafür verantwortlich, den vollständigen Datenabruf sicherzustellen, indem ein auf Zeitstempeln basierender Cursor beibehalten wird. NordPass wiederholt keine verpassten Ereignisse und sendet Ihnen auch keine Push-Nachrichten. Die integrierende Partei ist für die Implementierung dieses Musters verantwortlich, um einen lückenlosen Audit-Trail zu gewährleisten.

Um einen vollständigen Datenabruf zu gewährleisten, befolgen Sie diese Schritte:

1. Nehmen Sie aus der empfangenen API-Anforderung die neueste/zuletzt empfangene Aktivität (jede Aktivität hat ihren eigenen Zeitstempel, wann sie stattgefunden hat) und überprüfen Sie ihren Zeitstempel.
2. Verwenden Sie beim Erstellen einer neuen API-Anforderung diesen Filter:
   {
   "timestamp_from": TIMESTAMP_OF_LAST_RECEIVED_ACTIVITY + 1
   }
   
   Hinweis: Der Filter "timestamp_to": CURRENT_TIMESTAMP kann optional verwendet werden, um die Anzahl der Ergebnisse zu begrenzen.
   
    
3. So erhalten Sie auch bei kurzen Dienstunterbrechungen immer die neuesten Aktivitäten. Sobald der Dienst wieder verfügbar ist, bleibt der Filter aktiv, sodass Sie die aktuellsten Informationen aus dem Aktivitätsprotokoll ohne Lücken erhalten.

Ratenbegrenzungen

Die API ist auf 2.000 Anfragen pro 5 Minuten pro IP-Adresse beschränkt.

Antworten

Eine Liste der Aktionen, die von Mitgliedern Ihrer Organisation durchgeführt wurden, finden Sie im Abschnitt Aktionstypen der Aktivitätsprotokoll-Anleitung.

{
			    "data": [
			        {
			            "type": string,
			            "action": string,
			            "timestamp": integer,
			            "organization_uuid": string($uuid),
			            "user": {
			                "uuid": string($uuid),
			                "email": string($email)
			            },
			            "metadata": []
			        }
			    ],
			    "metadata": {
			        "total": integer, 
			        "per_page": integer, 
			        "current_page": integer, 
			        "total_pages": integer,
			    }
			}

Begrenzung

Die API kann bis zu 10.000 der neuesten Aktivitätsprotokoll-Datensätze zurückgeben (z. B. werden bei der Anforderung der Protokolle 9980–10050 keine Ergebnisse zurückgegeben). Wenn die Filterergebnisse dieses Limit überschreiten, werden nur die letzten 10.000 Ergebnisse zurückgegeben.

Fehlercodes