Verwenden eines HTTP-Clients

Aus RAD Studio
Wechseln zu: Navigation, Suche

Nach oben zu Verwenden der RTL in geräteübergreifenden Anwendungen


Die RTL enthält zwei Komponenten, mit denen Sie HTTP-Anforderungen an Server senden und deren Antworten verwalten können:

Hinweis: Alternativ können Sie eine Instanz von THTTPClient zum Verwalten Ihrer HTTP-Anforderungen verwenden.

Konfigurieren Ihre Anwendung beim Entwurf

Erstellen eines HTTP-Clients

Um einen HTTP-Client zu erstellen, mit dem Sie HTTP-Anforderungen senden können, ziehen Sie eine TNetHTTPClient-Komponente aus der Tool-Palette in ein Formular oder ein Datenmodul Ihrer Anwendung. Für die Komponente TNetHTTPClient ist keine Anfangskonfiguration erforderlich.

Erstellen und Konfigurieren von HTTP-Anforderungen

Sie müssen auch mindestens eine TNetHTTPRequest-Komponente in Ihr Formular oder Datenmodul aufnehmen.

Wenn Sie die neue HTTP-Anforderungs-Komponente eingefügt haben, doppelklicken Sie im Objektinspektor auf deren Eigenschaft Client, damit der Wert auf die zuvor hinzugefügte HTTP-Client-Komponente gesetzt wird.

Sie können eine beliebige Anzahl von Anforderungs-Komponenten verwenden. Wenn Sie mehrere unterschiedliche HTTP-Anforderungen senden müssen, wäre das geeignetere Vorgehen jedoch, nur eine HTTP-Anforderungs-Komponente zu verwenden und diese zur Laufzeit für jede Anforderung neu zu konfigurieren.

Senden einer Anforderung und Behandeln der Antwort

Senden einer HTTP-Anforderung

Um eine HTTP-Anforderung zu senden, müssen Sie mindestens Folgendes angeben:

Die HTTP-Anforderungsmethode bestimmt die Aktion, die der Server für die Ressource an dem angegebenen URL ausführen soll, z. B. Senden der Daten der Ressource oder Aktualisieren der Ressource mit Daten aus der Anforderung.

Wie eine HTTP-Anforderung mit einer TNetHTTPRequest-Komponente gesendet wird, hängt von der HTTP-Anforderungsmethode ab, die Sie verwenden möchten.

Hinweis: Funktionen, die eine Anforderung senden, entweder Execute oder methodenspezifische Funktionen, sind alle blockierend. Das heißt, diese Funktionen kehren erst zurück, wenn eine Antwort vom Server vorliegt. Siehe Verfolgen des Fortschritts beim Herunterladen der Antwortdaten weiter unten.

Senden einer HTTP-Anforderung mit den HTTP-Anforderungsmethoden DELETE, GET, HEAD, OPTIONS oder TRACE

Die folgenden HTTP-Anforderungsmethoden benötigen als Eingabedaten nur den Zielressourcen-URL:

Konfigurieren Sie Ihre Anforderung zuerst beim Entwurf, um eine HTTP-Anforderung mit einer dieser HTTP-Anforderungsmethoden zu senden:

  1. Konfigurieren Sie die Eigenschaft URL mit dem URL der Zielressource.
  2. Konfigurieren Sie die Eigenschaft MethodString mit dem Namen der HTTP-Anforderungsmethode, die Sie verwenden möchten.
Hinweis: Namen von HTTP-Anforderungsmethoden berücksichtigen die Groß-/Kleinschreibung.

Rufen Sie dann Execute auf, um Ihre Anforderung zu senden.

Senden einer HTTP-Anforderung mit den HTTP-Anforderungsmethoden MERGE, PATCH oder PUT

Die folgenden HTTP-Anforderungsmethoden benötigen außer dem Zielressourcen-URL Eingabedaten:

Um eine HTTP-Anforderung mit einer dieser HTTP-Anforderungsmethoden zu senden, rufen Sie die zugehörige Funktion auf (siehe die folgenden Tabelle). Geben Sie in Ihrem Aufruf den URL der Zielressource als erstes Argument und eine Instanz von TStream als zweites Argument an.

HTTP-Anforderungsmethode TNetHTTPRequest-Funktion
PUT Put
PATCH Patch
MERGE Merge
PATCH über PUT* PatchAlternative
MERGE über PUT* MergeAlternative
* Einige HTTP-Proxies unterstützen die neuesten Standard-HTTP-Anforderungsmethoden (wie PATCH) oder Nicht-Standard-HTTP-Anforderungsmethoden (wie MERGE) nicht. In diesen Fällen können Sie die HTTP-Anforderungsmethoden über andere HTTP-Anforderungsmethoden tarnen. Dazu müssen in der Anforderung Header enthalten sein, die die gewünschte HTTP-Anforderungsmethode angeben.

Senden einer HTTP-Anforderung mit der HTTP-Anforderungsmethode POST

Die HTTP-Anforderungsmethode POST (EN) benötigt außer dem Zielressourcen-URL Eingabedaten.

Um eine HTTP-Anforderung mit der HTTP-Anforderungsmethode POST zu senden, rufen Sie Post auf. In Ihrem Aufruf müssen Sie den URL der Zielressource als erstes Argument angeben. Die anderen Argumente hängen davon ab, wie Sie die Eingabedaten für Ihre Anforderung zur Verfügung stellen möchten:

  • Um den Inhalt einer lokalen Datei zu senden, geben Sie den lokalen Pfad zu dieser Datei als zweites Argument Ihres Aufrufs an.
  • Um den Inhalt eines Streams zu senden, geben Sie Ihre Instanz von TStream als zweites Argument Ihres Aufrufs an.
  • Um Formulardaten zu senden, die entsprechend dem HTML 4-Standard (EN) als mehrteilige MIME-Nachricht codiert sind, geben Sie Ihre Instanz von TMultipartFormData als zweites Argument Ihres Aufrufs an.
  • Um den Inhalt einer String-Liste zu senden, geben Sie Ihre Instanz von TStrings als zweites Argument Ihres Aufrufs an, und falls Ihre Strings nicht in UTF-8 codiert sind, geben Sie eine Instanz von TEncoding als viertes Argument an. Zum Beispiel:
Delphi:
NetHTTPRequest1.Post('http://www.example.com/rest/items', String1, nil, TEncoding.Default);
C++:
NetHTTPRequest1->Post("http://www.example.com/rest/items", String1, NULL, TEncoding::Default);

Behandeln einer HTTP-Antwort

Wenn der Zielserver eine Antwort auf Ihre Anforderung sendet, wird das Ereignis OnRequestCompleted Ihrer HTTP-Anforderungs-Komponente ausgelöst. Definieren Sie eine Ereignisbehandlungsroutine für dieses Ereignis, um die Daten aus der Serverantwort zu lesen. Wenn während Ihrer Anforderung ein Fehler auftritt, wird stattdessen das Ereignis OnRequestError Ihrer HTTP-Anforderungs-Komponente ausgelöst.

Die Ereignisbehandlungsroutine von OnRequestCompleted erhält zwei Parameter:

  • Sender ist Ihre HTTP-Anforderungs-Komponente.
  • AResponse ist ein Objekt, das das Interface IHTTPResponse implementiert.

Sie können alle Antwortdaten aus AResponse abrufen:

Verwalten von Cookies

Mit der Eigenschaft AllowCookies der HTTP-Client-Komponente können Sie festlegen, ob Sie die vom Server in der Antwort gesendeten Cookies akzeptieren möchten. Wenn AllowCookies True ist, speichert der HTTP-Client die empfangenen Cookies in seinem CookieManager.

Hinweis: Der HTTP-Client fügt seine vorhandenen Cookies immer der Anforderung hinzu, unabhängig vom Wert von AllowCookies.

Behandeln von Umleitungen

Mit der Eigenschaft HandleRedirects steuern Sie, wie die HTTP-Client-Komponente Umleitungen behandelt. Der Standardwert ist True, was bedeutet, dass die HTTP-Client-Komponente Umleitungen automatisch folgt.

Mit der Eigenschaft MaxRedirects der HTTP-Client-Komponente geben Sie die maximale Anzahl an Umleitungen an, der die Komponente folgen darf. Wenn die HTTP-Client-Komponente die angegebene Anzahl an maximalen Umleitungen erreicht, löst sie eine Exception mit dem Typ ENetHTTPRequestException aus.

Behandeln des Herunterladens der Antwortdaten

Beim Herunterladen der Antwort auf Ihre Anforderung durch den HTTP-Client wird laufend das Ereignis OnReceiveData Ihrer HTTP-Anforderung ausgelöst. Sehen Sie eine Ereignisbehandlungsroutine für OnReceiveData vor, um den Fortschritt beim Herunterladen der Antwortdaten zu verfolgen. Ihre Ereignisbehandlungsroutine erhält die folgenden Parameter:

  • Sender ist Ihr HTTP-Anforderungsobjekt.
  • AContentLength ist die erwartete Länge der Antwortdaten in Byte.
  • AReadCount ist die Länge der Antwortdaten in Byte, die der HTTP-Client bisher heruntergeladen hat.
  • Abort ist ein boolescher Parameter zum Abbrechen des Herunterladens.

Am Ende des Herunterladens wird OnReceiveData zum letzten Mal ausgelöst, und AContentLength und AReadCount enthalten die gleichen Werte. Kurz danach wird OnRequestCompleted ausgelöst.

Verfolgen des Fortschritts beim Herunterladen der Antwortdaten

Verwenden Sie zum Verfolgen des Fortschritts der heruntergeladenen Daten die Werte von AContentLength und AReadCount in der Ereignisbehandlungsroutine OnReceiveData. In folgendem Beispiel wird der Prozentsatz der heruntergeladenen Daten berechnet:

Delphi:
procedure TForm1.NetHTTPRequest1ReceiveData(const Sender: TObject;
AContentLength, AReadCount: Int64; var Abort: Boolean);
var
    percentageDownloaded:Double;
begin
    if AContentLength > 0 then
        percentageDownloaded :=  (AReadCount / AContentLength) * 100;
    else
        // the server did not provide the Content-Length header
end;
C++:
void __fastcall TForm1::NetHTTPRequest1ReceiveData(TObject * const Sender, __int64 AContentLength,
     __int64 AReadCount, bool &Abort)
{
    float percentageDownloaded;
    if (AContentLength > 0)
    {
        percentageDownloaded = ((float)AReadCount / (float)AContentLength) * 100.f;
    }
    else
    {
        // the server did not provide the Content-Length header
    }
}

Abbrechen des Herunterladens der Antwortdaten

Ändern Sie in der Ereignisbehandlungsroutine OnReceiveData den Wert von Abort in True, um das Herunterladen der Antwortdaten abzubrechen.

Senden einer Anforderung mit benutzerdefinierten Headern

Sie können sowohl mit der HTTP-Client-Komponente als auch mit der HTTP-Anforderungs-Komponente benutzerdefinierte Header festlegen. Folgende benutzerdefinierte Header können Sie festlegen:

Beim Ausführen einer Anforderung kombiniert die Methode THTTPClient.Execute des HTTP-Frameworks die benutzerdefinierten Header aus der HTTP-Client-Komponente und aus der entsprechenden HTTP-Anforderungs-Komponente und fügt diese Header der endgültigen Anforderung hinzu.

Behandeln von sicheren Verbindungen

Die HTTP-Client-Komponente unterstützt sichere Verbindungen (HTTPS). Das HTTP-Framework behandelt jede auftretende Zertifikatsanforderung automatisch und löst bei Bedarf das passende Ereignis aus:

Weitere Informationen über die Behandlung von Zertifikaten finden Sie in den Abschnitten Behandeln serverseitiger Zertifikate und Behandeln clientseitiger Zertifikate.

Behandeln von Authentifizierung und Zertifikaten

Behandeln der HTTP-Basiszugriffsauthentifizierung

Wenn Sie eine HTTP-Anforderung an einen Server senden, der eine HTTP-Basiszugriffsauthentifizierung erfordert, wird das Ereignis OnAuthEvent Ihres HTTP-Client-Objekts ausgelöst. Um Ihre Anmeldedaten für den Zugriff zu übermitteln, erstellen Sie eine Ereignisbehandlungsroutine für dieses Ereignis. Falls der Wert des zweiten Parameters, den die Ereignisbehandlungsroutine erhält (AnAuthTarget), TAuthTargetType.Server ist, füllen Sie die Variablen AUserName und APassword mit Ihrem Benutzernamen und Passwort für den Proxy. Zum Beispiel:

Delphi:
procedure TForm1.NetHTTPClient1AuthEvent(const Sender: TObject;
  AnAuthTarget: TAuthTargetType; const ARealm, AURL: string;
  var AUserName, APassword: string; var AbortAuth: Boolean;
  var Persistence: TAuthPersistenceType);
begin
  if AnAuthTarget = TAuthTargetType.Server then
  begin
    AUserName := 'MyUsername';
    APassword := '1234';
  end;
end;
C++:
void __fastcall TForm1::NetHTTPClient1AuthEvent(TObject * const Sender,
  TAuthTargetType AnAuthTarget, const UnicodeString ARealm,
  const UnicodeString AURL, UnicodeString &AUserName, UnicodeString &APassword,
  bool &AbortAuth, TAuthPersistenceType &Persistence)
{
    if (AnAuthTarget == TAuthTargetType::Server) {
        AUserName = "MyUsername";
        APassword = "1234";
    }
}

Ihre Ereignisbehandlungsroutine erhält auch den Bereich des HTTP-Servers, für den eine Authentifizierung erforderlich ist (ARealm), und den Ziel-URL Ihrer Anforderung (AURL).

Um die HTTP-Authentifizierung abzubrechen, ändern Sie den Wert von AbortAuth in True.

Senden einer Anforderung hinter einem Proxy

Wenn Sie sich hinter einem Proxy befinden, für den eine Authentifizierung erforderlich ist, können Sie die Proxy-Einstellungen festlegen, die für die Authentifizierung verwendet werden. Das folgende Beispiel zeigt das Vorgehen dabei:

Delphi:
NetHTTPClient1.ProxySettings := TProxySettings.Create('192.168.1.1', 8080, 'MyUserName', 'MyPassword');
C++:
TProxySettings  MyProxySettings("192.168.1.1", 8080, "MyUserName", "MyPassword", "");
NetHTTPClient1->ProxySettings = MyProxySettings;

Eine andere Möglichkeit zum Festlegen Ihrer Proxy-Einstellungen stellt ein URL-String mit den Proxy-bezogenen Informationen dar:

Delphi:
NetHTTPClient1.ProxySettings := TProxySettings.Create('http://MyUserName:[email protected]:8080');
C++:
TProxySettings  MyProxySettings("http://MyUserName:[email protected]:8080");
NetHTTPClient1->ProxySettings = MyProxySettings;

Alternativ können Sie die Anmeldeinformationen für die Proxy-Authentifizierung in der Ereignisbehandlungsroutine OnAuthEvent angeben. Siehe den Abschnitt Behandeln der HTTP-Basiszugriffsauthentifizierung. Der Wert von AnAuthTarget muss TAuthTargetType.Proxy anstelle von TAuthTargetType.Server sein.

Behandeln von System-Proxy-Einstellungen mit einem HTTP-Client

In der folgenden Tabelle wird erklärt, wie der HTTP-Client die System-Proxy-Einstellungen auf verschiedenen Plattformen behandelt:

Plattform Verhalten

Windows

Der HTTP-Client verwendet die System-Proxy-Einstellungen. Sie können die System-Proxy-Einstellungen umgehen und alternative Proxy-Einstellungen für den HTTP-Client bereitstellen. Um die System-Proxy-Einstellungen zu umgehen, erstellen Sie Proxy-Einstellungen für den HTTP-Client und geben http://direct als URL an.

macOS

Der HTTP-Client verwendet immer die System-Proxy-Einstellungen. Auch wenn Sie alternative Proxy-Einstellungen für den HTTP-Client bereitstellen, verwendet der HTTP-Client die System-Proxy-Einstellungen.

iOS

Der HTTP-Client verwendet immer die System-Proxy-Einstellungen. Auch wenn Sie alternative Proxy-Einstellungen für den HTTP-Client bereitstellen, verwendet der HTTP-Client die System-Proxy-Einstellungen.

Android

Der HTTP-Client verwendet die System-Proxy-Einstellungen. Sie können diese Einstellungen nicht umgehen, aber Sie können alternative Proxy-Einstellungen für den HTTP-Client bereitstellen.

Linux

Der HTTP-Client verwendet die System-Proxy-Einstellungen. Sie können diese Einstellungen nicht umgehen, aber Sie können alternative Proxy-Einstellungen für den HTTP-Client bereitstellen.

Hinweis: Wenn das System keine Proxy-Einstellungen festlegt (die Verbindung ist direkt), wird dies auch als "Einstellung" betrachtet. Unter iOS oder macOS ohne System-Proxy-Einstellungen können Sie beispielsweise keine Proxy-Einstellungen für den HTTP-Client bereitstellen. Die Einstellungen, die Sie bereitstellen, werden ignoriert, weil die Systemeinstellungen (die Einstellung "Kein Proxy") verwendet werden.
Achtung: Bis RAD Studio 10.4 hat die HTTP-Client-Bibliothek die NSURLConnection-API verwendet. Apple hat diese Bibliothek für Mac OS X 10.11 und iOS 9 als veraltet erklärt. Ab RAD Studio10.4.1 wird die neuere NSURLSession-API auf beiden Plattformen unterstützt. Dadurch werden auch Probleme mit der Proxy-Unterstützung unter macOS behoben.

Verwalten der Speicherung von Benutzer-Anmeldeinformationen

Mit TNetHTTPClient können Sie Anmeldeinformationen für die HTTP- oder Proxy-Authentifizierung speichern. Gespeicherte Anmeldeinformationen können einen Benutzernamen, ein Passwort, einen Zieltyp für die Authentifizierung, einen Bereich und einen Ziel-URL umfassen.

Das folgende Beispiel zeigt, wie mit TNetHTTPClient.CredentialsStorage Anmeldeinformationen gespeichert werden und dann mit diesen Anmeldeinformationen die Authentifizierung bei der Verbindung mit einem HTTP-Server, der eine grundlegende Authentifizierung erfordert, vorgenommen wird:

  1. Erstellen der Anmeldeinformationen und Hinzufügen zu Ihrem Anmeldeinformationsspeicher:
    Delphi:
    NetHTTPClient1.CredentialsStorage.AddCredentials(TCredentialsStorage.TCredential.Create(TAuthTargetType.Server, '', '', 'MyUserName', 'MyPassword');
    C++:
    TCredentialsStorage::TCredential *MyCredential = new TCredentialsStorage::TCredential(TAuthTargetType::Server, "", "", "MyUserName", "MyPassword");
NetHTTPClient1->CredentialsStorage->AddCredential(*MyCredential);
  2. Verwenden der gespeicherten Anmeldeinformationen. Sie können beispielsweise eine OnAuthEvent-Ereignisbehandlungsroutine schreiben, in der Sie:
    • Mit TCredentialsStorage.FindAccurateCredential nach Anmeldeinformationen suchen, die dem erforderlichen Authentifizierungstyp entsprechen (TAuthTargetType.Server).
    • Den Benutzernamen und das Passwort aus den entsprechenden Anmeldeinformationen für die Authentifizierung verwenden.
    Delphi:
    procedure TForm1.NetHTTPClient1AuthEvent(const Sender: TObject;
  AnAuthTarget: TAuthTargetType; const ARealm, AURL: string; var AUserName,
  APassword: string; var AbortAuth: Boolean;
  var Persistence: TAuthPersistenceType);
var
    MyCredential: TCredentialsStorage.TCredential;
begin
    MyCredential := NetHTTPClient1.CredentialsStorage.FindAccurateCredential(AnAuthTarget, '');
    AUserName := MyCredential.UserName;
    APassword := MyCredential.Password;
end;
    C++:
    void __fastcall TForm2::NetHTTPClient1AuthEvent(TObject * const Sender, TAuthTargetType AnAuthTarget,
  const UnicodeString ARealm, const UnicodeString AURL,
  UnicodeString &AUserName, UnicodeString &APassword, bool &AbortAuth,
  TAuthPersistenceType &Persistence)
{
    TCredentialsStorage::TCredential MyCredential;

    MyCredential = NetHTTPClient1->CredentialsStorage->FindAccurateCredential(AnAuthTarget, "");
    AUserName = MyCredential.UserName;
    APassword = MyCredential.Password;
}

Behandeln serverseitiger Zertifikate

Wenn der Server ein SSL-Zertifikat bereitstellt, dieses Zertifikat aber ungültig ist, wird das Ereignis OnValidateServerCertificate ausgelöst. Erstellen Sie eine Ereignisbehandlungsroutine für OnValidateServerCertificate, damit Sie das Serverzertifikat (Certificate) überprüfen und festlegen können, ob Sie es akzeptieren oder nicht. Wenn Sie das Serverzertifikat akzeptieren, ändern Sie den Wert des Parameters Accept in True.

Behandeln clientseitiger Zertifikate

Wenn für den Server ein Client-Zertifikat erforderlich ist, wird das Ereignis OnNeedClientCertificate ausgelöst. Erstellen Sie eine Ereignisbehandlungsroutine für OnNeedClientCertificate, damit Sie Ihre Liste der Client-Zertifikate (ACertificateList) überprüfen und das Zertifikat festlegen können, das Sie an den Server senden möchten. Um ein Zertifikat aus der Liste zu senden, ändern Sie den Wert von AnIndex in den Index des Zielzertifikats in ACertificateList.

Hinweis: Wenn die HTTP-Methode der ersten Anforderung an einen Server, der ein clientseitiges Zertifikat erfordert, nicht HEAD oder GET ist (sondern z. B. POST), dann lautet der Statuscode der Serverantwort 413. Senden Sie immer zuerst eine HEAD- oder GET-Anforderung. Eine HEAD-Anforderung ist normalerweise vorzuziehen, weil weniger Daten übertragen werden.

Anfragen asynchron machen

Anfragen sind standardmäßig synchron. Während der Anfrage wird die Ausführung Ihrer Anwendung gestoppt, wenn Sie Ihre Anfrage starten, und wird nur fortgesetzt, wenn Sie eine Antwort vom Server oder der Anfrage-Zeitüberschreitung erhalten.

Wenn Sie möchten, dass Ihre Anfrage asynchron sind, damit die Anfragen nicht bei der Ausführung nicht gestoppt werden, müssen Sie die Asynchronous-Eigenschaft der Client-Komponente oder die Asynchronous-Eigenschaft der Anfragekomponente aktivieren, abhängig von der Komponente, mit der Sie Ihre Anforderung ausführen möchten.

Siehe auch

Abgerufen von „https://docwiki.embarcadero.com/RADStudio/Alexandria/d/index.php?title=Verwenden_eines_HTTP-Clients&oldid=219246“