Zum Hauptinhalt springen

Transportschicht für REST-Dienste

In diesem Thema wird erklärt, wie Sie einen REST-Dienst mit der @jutro/transport-Schicht erstellen können, um HTTP-Anfragen zu senden und zu empfangen.

Der Jutro-Transport enthält die folgenden Optionen für das Senden und Empfangen von Anfragen:

  • HttpRequestBuilder - Ein erweiterbarer Wrapper um „fetch“ zum Ausführen von REST-Aufrufen. Er bietet ein Array von „Option“-Resolvern, um Optionen und Header in die Anfrage einzufügen. Er bietet Ihnen auch Encoder/Decoder zum Transformieren der gesendeten und empfangenen Daten und stellt Callbacks bereit, um den Ablauf Anforderung -> Antwort -> Ausnahme zu überwachen.
  • createHttpRequest – Erzeugt die http-Anfrage unter Verwendung von HttpRequestBuilder.
  • createJsonHttpRequest – Erstellt eine http-Anfrage, gibt aber den JSON-Inhaltstyp an, sodass der Server weiß, in welcher Form er die Daten senden soll.
  • basicAuthOptions – Wird verwendet, um einen Benutzernamen und ein Kennwort mit einfacher Authentifizierung in einem REST-Aufruf zu übergeben - wir empfehlen dringend stattdessen authTokenHandler mit Jutro-Authentifizierung zu verwenden.
  • jsonOptions – Bietet einen JSON-Header für Anfragen mit JSON-Nutzdaten
  • langLocaleOptions – Stellt gw-language- und gw-locale-Header für Anfragen bereit.
  • analyticsHandler – Behandelt die Übergabe von Ereignis-Nutzdaten in der http-Anfrage an eine eventTopicMap, sodass sie an eine Analyse-Engine gesendet werden können.
  • authTokenHandler – Erstellt Authentifizierungsoptionen unter Verwendung eines Bearer-Tokens der Jutro-Authentifizierung zur Übergabe an HttpRequestBuilder.
  • zipkinTraceHandler – Bietet eine Erweiterung für Verfolgungsoptionen.

createHttpRequest​

So erstellen Sie eine http-Anfrage als REST-Dienst:

  1. Importieren Sie createHttpRequest aus @jutro/transport:

    import { createHttpRequest, jsonOptions } from '@jutro/transport';

  2. Erstellen Sie eine Variable wie die folgende restService-Variable:

    const getRestService = () => {
      const baseUrl = 'https://test.com';

      return createHttpRequest(baseUrl, true).addOptions(jsonOptions).build();
    };

  3. Erstellen Sie eine Funktion, die die Anforderung ausführt:

    const postRequest = (url, data) => getRestService().post(url, data);

Sie können Optionen als letztes Argument von Funktionen wie get() oder post() übergeben.

const postRequest = (url, data) =>
  getRestService().post(url, data, authTokenHandler);

Wenn Sie benutzerdefinierte Header in Ihre Anfrage einfügen möchten, können Sie diese mit .addOptions wie folgt übergeben:

const getRestService = () => {
  const baseUrl = 'https://test.com';

  return createHttpRequest(baseUrl, 'unauthenticated', true)
    .addOptions({
      headers: { 'Content-Type': 'application/json; charset=UTF-8' },
    })
    .build();
};

Feld für Autorisierungsanfrage – HTTP-Header​

Sie können einen Autorisierungs-Header in Ihren REST-Dienst einfügen, indem Sie authTokenHandler mit den Funktionen get() oder post() oder die addHandler()-Methode verwenden.

In der Standardimplementierung erhält authTokenHandler das Authentifizierungs-Token und fügt den Authorization-Header zusammen mit 'GW-Tenant' und 'GW-User' auf der Grundlage der im Token gespeicherten Daten hinzu.

Bei jedem API-Aufruf, mit dem ein Workset, eine Ressource oder ein Tenant erstellt oder geändert wird, muss die Anfrage die Benutzerkennung 'GW-User', uid, enthalten.

Die folgenden Faustregeln gelten für die Verwendung von 'GW-User' als Teil eines API-Aufrufs:

  1. Wenn der API-Aufruf für die Autorisierung ein Benutzerzugriffstoken verwendet, muss der Header „GW-User“ mit einem uid-Claim in diesem Token übereinstimmen. Ein Aufruf wird abgelehnt, wenn es eine Nichtübereinstimmung zwischen dem Header und dem Token gibt.
  2. Wenn der API-Aufruf ein Dienstzugriffs-Token zur Autorisierung verwendet, muss der Header „GW-User“ eine uid des Benutzers enthalten, der die ursprüngliche Aktion initiiert hat. Die Benutzer-ID kann nach einer Anmeldung bei einem vorgelagerten Dienst vom Zugriffstoken abgerufen werden.

Weitere Informationen über den Header der Autorisierungsanfrage finden Sie in der Dokumentation zur Autorisierung.

import {
  authTokenHandler,
  HttpRequestBuilder,
  jsonOptions,
} from '@jutro/transport';

export const getRestService = (baseUrl) => {
  const request = new HttpRequestBuilder(baseUrl)
    .addOptions(jsonOptions)
    .addHandler(authTokenHandler);

  const requestService = request.build();
  return requestService;
};

Überschreiben von Handlern für Zugriff auf Antwort-Header​

Die Transportschicht ist ein Mechanismus zum Abrufen von Daten von einem Endpunkt, die vom Frontend verarbeitet werden sollen, und jeder der Handler innerhalb dieser Schicht ist eigentlich ein Hook, der es Ihnen ermöglicht, den Abrufprozess in verschiedenen Phasen abzufangen. onErrorResponse und onException bieten Ihnen zum Beispiel die Möglichkeit, Fehler zu verwalten, die während des Abrufprozesses auftreten können.

Der Jutro-Transport bietet die folgenden Handler:

  • onAuth: für die Authentifizierung
  • onFetch: ermöglicht es Ihnen, den zugrundeliegenden Fetch-Aufruf in etwas anderes zu ändern.
  • onErrorResponse: um eine Dienst-Fehlerantwort wie einen 404- oder 500-Fehler zu bearbeiten
  • onException: um unerwartete Ausnahmen wie Netzwerkfehler zu verwalten.
  • onResponse: sobald die Daten abgerufen wurden, verwenden Sie onResponse, um die Daten zu analysieren oder eine Operation mit ihnen durchzuführen.
  • onTrace: ermöglicht es Ihnen, verschiedene Trace-Handler hinzuzufügen.

Um auf die in einer Anfrage zurückgegebenen Antwort-Header zuzugreifen, können Sie das Standardverhalten überschreiben, indem Sie den Handler zu HttpRequestBuilder hinzufügen, der nach der Erstellung von createHttpRequest zurückgegeben wird, und der Anfrage eine neue Operation zuweisen.

Dazu fügen Sie den Callback zur addHandler-Methode im http Request Builder hinzu.

Das folgende Beispiel zeigt, wie Sie die standardmäßige onResponse- und onErrorResponse-Antwort überschreiben können, um das Antwort-Header-Objekt zu ändern:


import { createHttpRequest } from '@jutro/transport';

...

const responseSuccess = fullResponse => Promise.resolve(fullResponse);

const responseError = fullResponse => Promise.reject(fullResponse);

const pokeService = createHttpRequest('https://pokeapi.co/api/v2/', false) // don't miss the trailing slash
    .addHandler('onResponse', responseSuccess)
    .addHandler('onErrorResponse', responseError)
    .build();

pokeService
    // to get an error response change to 'https://pokeapi.co/api/v2/pokemon/pika'
    .get('pokemon/pikachu', {})
    .then(fullResponse => {
        console.log(fullResponse, 'success');
        console.log(Object.fromEntries(fullResponse.headers), 'success headers');
    })
    .catch(fullResponse => {
        console.log(fullResponse, 'failure');
        console.log(Object.fromEntries(fullResponse.headers), 'failure headers');
    });

Beispiele für Antwortobjekte bei Erfolg und Fehler​

Nachfolgend finden Sie Beispiele für die oben aufgeführten Antwortobjekte für Fehler und Erfolg:

Antwortobjekt bei Fehler Antwortobjekt bei Fehler

Antwortobjekt bei Erfolg Antwortobjekt bei Erfolg

Note: Um auf zusätzliche Header zugreifen zu können, müssen Sie CORS konfigurieren.

Senden von Dateien​

Um eine Datei aus einem HTML-Formular (oder einem FormData-Objekt) zu senden, lassen Sie einfach den jsonOptions-Header weg, fetch fügt selbst einen multipart/form-data-Header mit einer Grenze-Annotation hinzu:

   import { createHttpRequest, authTokenHandler } from '@jutro/transport';

    ...

    restService = createHttpRequest(baseUrl)
        .addHandler(authTokenHandler)
        .build();

verwenden Sie dann restService wie folgt:

    ...

    const data = new FormData();
    data.append('file_property_name', FILE_OBJECT, 'FILE_NAME');

    restService.post('YOUR_URL', data) //executes your request, use .then() or async/await to handle the response

createJsonHttpRequest​

createJsonHttpRequest ist eine alte Implementierung, die die Verwendung des application/json Inhaltstyps erzwingt. Wenn Sie diese verwenden möchten, folgen Sie dem folgenden Beispiel:

   import { createJsonHttpRequest, authTokenHandler } from '@jutro/transport';

    ...

    restService = createJsonHttpRequest(baseUrl, false)
        .addHandler(authTokenHandler)
        .build();