API-Protokollseite im Jitterbit API Manager

Einführung

Die API-Protokolle-Seite im API Manager zeigt eine Tabelle aller API-Verarbeitungsprotokolle sowie Debug-Protokolle (wenn das Debug-Logging aktiviert ist). Protokolle werden für benutzerdefinierte, OData- und Proxy-APIs angezeigt, wenn sie über das Cloud-API-Gateway oder das private API-Gateway aufgerufen werden.

Es gibt vier Arten von Protokollen, die für einen API-Aufruf aufgezeichnet werden können:

• API-Protokolle: API-Protokolle werden automatisch auf der API-Protokolle-Seite für jeden API-Aufruf im API Manager generiert. API-Protokolle enthalten Informationen über den API-Aufruf, einschließlich des Zeitstempels der API-Anfrage, des HTTP-Statuscodes, der Anfrage-ID, der Anfragemethode, der Anfrage-URI, der Antwortzeit, der Quell-IP der aufrufenden Anwendung, der Quellanwendung und aller Protokollnachrichten.
• API-Debug-Protokolle: API-Debug-Protokolle sind zusätzliche Einträge in einem bestehenden API-Protokoll, die jede Anfrage vollständig nachverfolgen, die über die Dienst-URL einer API im API Manager empfangen wird. Das Debug-Logging für APIs ist standardmäßig nicht aktiviert und muss für jede einzelne API im API Manager aktiviert werden, damit API-Debug-Protokolle in einem API-Protokoll enthalten sind.
• API-Verbose-Protokolle: API-Verbose-Protokolle sind zusätzliche Einträge in einem bestehenden API-Protokoll, die aus Anfrage- und Antwortdaten bestehen, die über die Dienst-URL einer API im API Manager empfangen oder gesendet werden. Das Verbose-Logging für APIs ist standardmäßig nicht aktiviert und muss für jede einzelne API im API Manager aktiviert werden, damit API-Verbose-Protokolle in einem API-Protokoll enthalten sind.
• API-Betriebsprotokolle: API-Betriebsprotokolle enthalten den Beginn eines API-Aufrufs und die verstrichene Zeit. Im Gegensatz zu API-Protokollen, Debug-Protokollen und Verbose-Protokollen erfordern API-Betriebsprotokolle die Verwendung eines privaten Agents und sind in der Konfigurationsdatei des privaten Agents aktiviert. Diese Protokolle werden auf dem privaten Agenten in der Datei jitterbit.log, die sich im Verzeichnis log befindet, aufgezeichnet.

Die Protokolldaten für API-Protokolle, Debug-Protokolle und Verbose-Protokolle sind auf der API-Protokolle-Seite 90 Tage ab dem Datum verfügbar, an dem die API verwendet wird.

Für weitere Informationen zum Aktivieren von Debug-Protokollen und ausführlichen Protokollen siehe diese Ressourcen:

• Schritt 1: Einstellungen der benutzerdefinierten API-Konfiguration
• Schritt 1: Einstellungen der OData-Dienstkonfiguration
• Schritt 1: Grundeinstellungen der Proxy-API-Konfiguration

Um zusätzliche Protokollinformationen für OData-APIs, einschließlich SQL-Daten, die an die Datenbank gesendet werden, hinzuzufügen, bearbeiten Sie die Konfigurationsdatei des privaten Agents und setzen Sie DebugJDML auf true.

Zugriff auf die API-Protokollseite

Um auf die API-Protokoll-Seite zuzugreifen, verwenden Sie das Harmony-Portal-Menü, um API Manager > API-Protokolle auszuwählen.

Kopfzeile der API-Protokollseite

Die Kopfzeile oben auf der API-Protokoll-Seite enthält eine Suchleiste, Filter und zusätzliche Optionen:

Sie können die angezeigten Daten anpassen, indem Sie die Dropdown-Menüs Nach und Daten anzeigen verwenden.

Nach filtern

Die Dropdown-Menüs Nach ermöglichen es Ihnen, API-Protokolle basierend auf bestimmten Kriterien über jede Kombination von Umgebungen, APIs, Profilen, Statuscodes oder Anforderungsmethoden anzuzeigen.

Jeder Filter zeigt eine Dropdown-Liste von Kriterien an, aus der Sie ein oder mehrere Kriterien auswählen können.

Dies sind die verfügbaren Kriterien zum Filtern:

• Umgebungen: Verwenden Sie das Dropdown-Menü, um Umgebungen auszuwählen, in denen sich die APIs befinden. Wenn alle Filter nicht ausgewählt sind, werden die Umgebungen für alle APIs in der Organisation angezeigt, auf die Sie Zugriff haben.

• APIs: Verwenden Sie das Dropdown-Menü, um veröffentlichte APIs innerhalb der Organisation auszuwählen. Wenn alle Filter nicht ausgewählt sind, werden alle APIs in der Organisation angezeigt, auf die Sie Zugriff haben.

  Hinweis

  Zuvor veröffentlichte APIs, die nicht mehr veröffentlicht sind, erscheinen nicht im Dropdown-Menü APIs. API-Protokolle für diese APIs sind auf der Seite API-Protokolle vorhanden, können jedoch nicht gefiltert werden.

• Profile: Verwenden Sie das Dropdown-Menü, um die zugewiesenen Sicherheitsprofile der APIs auszuwählen. Wenn alle Filter nicht ausgewählt sind, werden alle Sicherheitsprofile in der Organisation angezeigt, auf die Sie Zugriff haben.

• Statuscodes: Verwenden Sie das Dropdown-Menü, um die Gruppen der HTTP-Antwortstatuscodes auszuwählen, und wählen Sie aus Erfolg (2xx), Umleitungen (3xx), Client-Fehler (4xx) und Server-Fehler (5xx). Wenn alle Filter nicht ausgewählt sind, werden alle HTTP-Antwortstatuscodes für APIs in den Organisationen angezeigt, auf die Sie Zugriff haben. Weitere Informationen zu Statuscodes finden Sie in den w3.org-Statuscode-Definitionen.

• Anforderungsmethoden: Verwenden Sie das Dropdown-Menü, um die HTTP-Anforderungsmethoden auszuwählen, und wählen Sie aus GET, PUT, POST, DELETE, PATCH und MERGE. Wenn alle Filter nicht ausgewählt sind, werden alle HTTP-Anforderungsmethoden für APIs in der Organisation angezeigt, auf die Sie Zugriff haben. Weitere Informationen zu HTTP-Anforderungsmethoden finden Sie in den w3.org-Anforderungsmethoden.

• API-Gateway: Sichtbar nur, wenn eine Organisation zwei oder mehr Cloud-API-Gateways verwendet. Verwenden Sie das Menü, um die Domain des Cloud-API-Gateways auszuwählen. Die Tabelle API-Protokolle zeigt Protokolle nur für die ausgewählte Domain an.

Daten anzeigen

Die Option Daten anzeigen ermöglicht es Ihnen, Protokolle innerhalb eines bestimmten Zeitraums anzuzeigen. Die Standardeinstellung für den Zeitraum ist Letzte 7 Tage.

Verwenden Sie das Dropdown-Menü Daten anzeigen, um den gewünschten Zeitraum auszuwählen. Wählen Sie einen der folgenden Zeiträume: Letzte 10 Minuten, Letzte 1 Stunde, Letzte 10 Stunden, Letzte 24 Stunden, Letzte 7 Tage, Letzte 1 Monat oder Benutzerdefinierter Zeitraum.

Die Auswahl von Benutzerdefiniertem Zeitraum ermöglicht es Ihnen, API-Protokolle innerhalb eines bestimmten Zeitraums der letzten 90 Tage anzuzeigen. Wenn diese Option ausgewählt ist, werden zusätzliche Kalenderfelder Von und Bis angezeigt:

• Von: Klicken Sie, um das Startdatum und die Uhrzeit für die API-Protokolle anzupassen.
• Bis: Klicken Sie, um das Enddatum und die Uhrzeit für die API-Protokolle anzupassen.

Nach dem Klicken auf die Kalenderfelder Von oder Bis wird ein Kalenderdialog angezeigt, in dem Sie das Datum und die Uhrzeit auswählen:

Suche

Die Suchleiste ermöglicht es Ihnen, die Protokolle nach den unten angegebenen Suchkriterien zu filtern:

• Nur Protokolle mit Nachrichten: Wählen Sie diese Option, um die Suchergebnisse weiter einzuschränken, sodass nur Protokolle angezeigt werden, die Protokolldetails enthalten. Die Suchergebnisse werden automatisch aktualisiert.

Suchkriterien

Dies sind die Suchkriterien, die verwendet werden können. Beispiele für gültige und ungültige Suchkriterien sind enthalten:

Kombinierte Suchen

Suchen können eine Kombination von Kriterien enthalten. Kombinierte Suchkriterien müssen durch ein Semikolon (;) zwischen jedem Kriterium getrennt werden. Dies sind Beispiele für gültige kombinierte Suchen:

message=%Access Denied%;requesturi=%contacts%;

requestid=%yzaccwui%;message=%REJECT%;
requesturi=%contacts%;responsetime<=2;
responsetime>=5;sourceapp=%Chrome%;
responsetime>=5;sourceip=70.5%;
sourceapp=%Chrome%;message=%REJECT%;

sourceapp=%Mozilla%;responsetime<=1;

sourceip=70.5%;requesturi=%contacts%;

Zusätzliche Optionen

Zusätzliche API-Protokolloptionen werden auf der linken Seite der Seite direkt über der Suchleiste angezeigt:

• Letzte Aktualisierung anzeigen: Zeigt die letzte Zeit an, zu der die Daten entweder dynamisch oder manuell aktualisiert wurden. Die Zeit wird im Format h:mm:ss angezeigt.

• Aktualisieren: Klicken Sie, um die Protokolldaten basierend auf den angewendeten Filtern und Suchkriterien zu aktualisieren.

• Als CSV herunterladen: Klicken Sie, um die aktuellen Protokolldaten basierend auf den angewendeten Filtern und Suchkriterien herunterzuladen.

  Hinweis

  Das Datumsfeld innerhalb der CSV-Datei ist ein UNIX-Zeitstempel, der konvertiert werden muss, wenn Sie ein anderes Datum- und Zeitformat verwenden möchten.

API-Protokolle anzeigen

Jede Zeile in der API-Protokolle-Tabelle zeigt API-Protokolldaten für einen API-Aufruf an:

• Zeitstempel: Der Zeitstempel der API-Anfrage. Zeiten werden in der Zeitzone Ihres Browsers angezeigt.
• Statuscode: Der HTTP-Statuscode. Weitere Informationen zu HTTP-Statuscodes finden Sie in den w3.org-Statuscode-Definitionen.
• Anforderungs-ID: Eine eindeutige ID für die API-Anfrage.
• Anforderungsmethode: Die HTTP-Anforderungsmethode der API (GET, PUT, POST, DELETE, PATCH oder MERGE).
• Anforderungs-URI: Die vollständige URL der aufgerufenen API. Fahren Sie mit der Maus über das Feld Anforderungs-URI, um die vollständige URL anzuzeigen.
• Antwortzeit: Die Zeit, in Millisekunden, die die API benötigt hat, um auszuführen.
• Quell-IP: Die externe IP-Adresse der Anwendung oder des Servers, der die API aufgerufen hat.
• Quellanwendung: Die Quellanwendung für den API-Aufruf, die nur vorhanden ist, wenn der API-Aufruf in einem Anfrage-Header übergeben wird. Fahren Sie mit der Maus über die Spalte Quellanwendung, um den Inhalt des Feldes anzuzeigen.

Jede Seite zeigt 20 Protokolle an. Sie können alle Protokolle innerhalb der Filter- und Suchkriterien mit den Schaltflächen Weiter und Zurück anzeigen.

Protokolldetails anzeigen

Um zusätzliche Protokolldetails oder Debug-Protokolle (falls aktiviert) anzuzeigen, klicken Sie auf das Erweiterungssymbol in einem Protokolleintrag:

Ein typisches API-Protokoll enthält diese Details:

• Harmony-Region-Domainname, Dienstpfad und Basis-URL (siehe API-Dienst-URL)
• Verarbeitungszeit des API-Aufrufs
• Sicherheitsprofilinformationen wie Autorisierungstyp und verwendete Anmeldeinformationen
• Payload-Details einschließlich Länge der Payload und Größe der Antwort
• Fehlerinformationen (falls zutreffend)
• Debug-Protokolle (falls aktiviert)
• Ausführliche Protokolle (falls aktiviert)

Wenn das Debug-Logging für eine API aktiviert ist und die API-Payload mehr als 10.000 Zeichen enthält, wird eine Schaltfläche Payload herunterladen für den Protokolleintrag angezeigt. Wenn Sie darauf klicken, wird eine ZIP-Datei der API-Payload auf Ihren lokalen Computer heruntergeladen.

API Manager Log Service API (Beta)

Als Alternative zum Herunterladen einer API-Protokolldatei durch Klicken auf Als CSV herunterladen können Sie eine API-Protokolldatei über eine REST-API abrufen. Dies erfordert die Verwendung von Befehlszeilen-Dienstprogrammen wie curl oder Anwendungen wie Postman.

Um die API Manager Log Service API (Beta) zu verwenden, nachdem Sie API-Protokolle aktiviert haben für die API Manager API (wie zuvor auf dieser Seite beschrieben), befolgen Sie diese Schritte:

1. Holen Sie sich ein Authentifizierungstoken über die User Service Controller API. Dieses Token ist erforderlich, um die API Manager Log Service API (Beta) zu verwenden.

   • Wenn Ihre Harmony Organisation keine Zwei-Faktor-Authentifizierung (TFA) aktiviert hat, holen Sie Ihr Authentifizierungstoken mit einer Standard-Anmeldeanforderung ab.

   • Wenn Ihre Harmony Organisation TFA aktiviert hat, erfordert das Abrufen des Authentifizierungstokens zwei Anfragen:

     1. TFA-Code abrufen

     2. Verwenden Sie den TFA-Code, um ein Authentifizierungstoken abzurufen

2. Protokolldatei abrufen mit der API Manager Log Service API (Beta).

Authentifizierungstoken abrufen

Das Abrufen eines Authentifizierungstokens erfordert die Verwendung der User Service Controller API.

Ein Beispiel für eine Anfrage, die das Anmelden in der NA-Region und das Abrufen des Autorisierungstokens zeigt:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!"
}'

Basis-URL

Die Basis-URL hängt von der Region ab, in der sich die Organisation befindet:

Header

Diese Header sind erforderlich:

Körperparameter

Diese erforderlichen Parameter werden im Körper der Anfrage übergeben:

Antwortkörper

Der zurückgegebene Antwortkörper enthält eine Liste der Organisationen, mit denen der Benutzer verbunden ist, zusätzlich zum Authentifizierungstoken ("authenticationToken"). Dieses Token ist erforderlich für die nachfolgende Autorisierung mit der API Manager Log Service API (Beta). In diesem Beispiel ist das Authentifizierungstoken "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4". Die Organisations-ID wird als "123456" für die erste Organisation angezeigt, zu der dieser Benutzer gehört. Ein Beispiel für die Antwort:

{
  "status": true,
  "operation": "User login",
  "authenticationToken": "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4",
  "serverUrl": "https://na-east.jitterbit.com",
  "cloudAppsUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [
    {
      "orgId": "123456",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "20970",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "123456",
  "sessionTimeoutInSeconds": 14400
}

Abrufen eines Authentifizierungstokens mit aktivierter TFA

Wenn die Organisation des Benutzers Harmony die Zwei-Faktor-Authentifizierung (TFA) aktiviert hat, erfordert das Abrufen des Authentifizierungstokens zwei Anfragen über die User Service Controller API:

1. TFA-Code abrufen

2. TFA-Code verwenden, um ein Authentifizierungstoken abzurufen

TFA-Code abrufen

Ein gültiger TFA-Code ist erforderlich, um ein Authentifizierungstoken abzurufen, wenn TFA aktiviert ist. Ein Beispiel für eine Anfrage, die das Einloggen in die NA-Region und das Anfordern eines TFA-Codes zeigt:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!",
    "deviceId": "abcd"
}'

Basis-URL

Die Basis-URL hängt von der Region ab, in der sich die Organisation befindet:

Header

Diese Header sind erforderlich:

Body-Parameter

Diese erforderlichen Parameter werden im Body der Anfrage übergeben:

Antwort-Body

Der zurückgegebene Antwort-Body enthält eine Fehlermeldung, die angibt, dass ein TFA-Code an die Email-Adresse des Benutzers gesendet wurde.

{
  "status": false,
  "operation": "User login",
  "errorCode": "VALIDATE_TFA_LOGIN_EMAIL",
  "errorMessage": "Validate your login with authentication code. An email from Jitterbit with the code was sent to you.",
  "authenticationToken": null,
  "serverUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [],
  "defaultOrgId": null
}

Verwenden Sie den TFA-Code, um ein Authentifizierungstoken abzurufen

Der an die Email-Adresse des Benutzers gesendete TFA-Code kann nun in der zweiten Anfrage verwendet werden, um das Authentifizierungstoken abzurufen. Ein Beispiel für eine Anfrage, die das Anmelden in der NA-Region mit einem TFA-Code und das Abrufen des Autorisierungstokens zeigt:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login/tfacode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!",
    "code": "112233",
    "deviceId": "abcd"
}'

Basis-URL

Die Basis-URL hängt von der Region ab, in der sich die Organisation befindet:

Header

Diese Header sind erforderlich:

Body-Parameter

Diese erforderlichen Parameter werden im Body der Anfrage übergeben:

Antwort-Body

Der zurückgegebene Antwort-Body enthält eine Liste der Organisationen, mit denen der Benutzer verbunden ist, zusätzlich zum Authentifizierungstoken ("authenticationToken"). Dieses Token ist für die nachfolgende Autorisierung mit der API Manager Log Service API (Beta) erforderlich. In diesem Beispiel ist das Authentifizierungstoken "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4". Die Organisations-ID wird als "123456" für die erste Organisation angezeigt, zu der dieser Benutzer gehört. Ein Beispiel für die Antwort:

{
  "status": true,
  "operation": "User login",
  "authenticationToken": "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4",
  "serverUrl": "https://na-east.jitterbit.com",
  "cloudAppsUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [
    {
      "orgId": "123456",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "654321",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "123456",
  "sessionTimeoutInSeconds": 14400
}

API-Protokolle asynchron abrufen (Beta)

Sobald Sie das Authentifizierungstoken und die Organisations-ID haben, können Sie API-Protokolle asynchron über die API Manager Log Service API (Beta) abrufen. Ein Beispiel, das zeigt, wie Sie alle Datensätze vom 20. Januar 2023 bis zum 20. Januar 2024 abrufen:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/api/analytics/debuglogs-async' \
--header 'Content-Type: application/json' --header 'Accept: application/json' --header 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4' \
--data-raw '{
    "ascendSort": false,
    "retrieveLogMessages": false,
    "timeRangeFrom": "01/20/2023 01:01:00 +0100",
    "timeRangeTo": "01/20/2024 01:01:00 +0100",
    "clientTimeZone": "Europe/Berlin",
    "queryString": "responsetime>5; sourceip=14.141%",
    "orgId": "123456",
    "csvFormat": true
}'

Basis-URL

Die Basis-URL hängt von der Region ab, in der sich die Organisation befindet:

Header

Diese Header können in der Anfrage verwendet werden:

Körperparameter

Diese Parameter können im Body der Anfrage übergeben werden:

Antwortkörper

Wenn erfolgreich, enthält der zurückgegebene Antwortkörper einen Referenzschlüssel zur Verfolgung und zum Herunterladen der API-Protokolldatei basierend auf den bereitgestellten Parametern:

{
    "key": "debug-log-E8D47FE1F172D3EE46C620791E614B78D111CE624485D2E1B3D482370690DC40",
    "status": "COMPLETE"
}

Der Referenzschlüssel kann dann als Teil des folgenden API-Aufrufs angegeben werden, um den Status der Protokolldatei zu überprüfen oder sie herunterzuladen, wenn der Status VOLLSTÄNDIG ist:

curl --location --request GET 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/api/analytics/log-async/{orgId}/{key}' \
--header 'Content-Type: application/json' --header 'Accept: application/json' --header 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4'

Mögliche Status sind:

• EMPFOHLEN: Harmony hat eine gültige Anfrage zum Generieren der Protokolldatei erhalten. Der Status wechselt zu VERARBEITEN, wenn die Anfrage ausgeführt wird.
• VERARBEITEN: Die Protokolldatei wird generiert. Der Status wechselt zu VOLLSTÄNDIG, wenn die Dateigenerierung abgeschlossen ist.
• VOLLSTÄNDIG: Die Protokolldatei ist bereit zum Herunterladen mit der oben genannten log-async API.
• UNGÜLTIG: Der Referenzschlüssel konnte nicht gefunden werden. Dieser Status wird nur gemeldet, wenn ein unbekannter oder fehlerhafter Referenzschlüssel an die log-async API übergeben wird.
• FEHLER: Der Referenzschlüssel wurde gefunden, nachdem die API versucht hatte, die Protokolldatei zu generieren, aber ein Fehler wurde gemeldet. Eine Fehlermeldung wird ebenfalls zurückgegeben, die erklärt, warum die Generierung fehlgeschlagen ist.
• KEINE_DATEN: Die Filterparameter, die Daten im ursprünglichen API-Aufruf abfragen, haben 0 Ergebnisse zurückgegeben.