Utilisation d'un client HTTP

De RAD Studio
Aller à : navigation, rechercher

Remonter à Utilisation de la RTL dans les applications multi-périphériques


La RTL fournit deux composants que vous pouvez utiliser pour envoyer des requêtes HTTP aux serveurs et gérer leurs réponses :

Remarque: Vous pouvez également utiliser une instance de THTTPClient pour gérer vos requêtes HTTP.

Configuration de votre application à la conception

Création d'un client HTTP

Pour créer un client HTTP permettant d'envoyer une requête HTTP, déplacez un composant TNetHTTPClient de la palette d'outils sur une fiche ou un module de données de votre application. Le TNetHTTPClient ne nécessite aucune configuration initiale.

Création et configuration de requêtes HTTP

Vous avez également besoin de déposer un ou plusieurs composants TNetHTTPRequest sur votre fiche ou module de données.

Dès que vous avez déposé votre nouveau composant requête HTTP, double-cliquez sur sa propriété Client dans l'inspecteur d'objets afin que sa valeur soit le composant client HTTP que vous avez déposé auparavant.

Vous pouvez utiliser n'importe quel nombre de composants requête. Néanmoins, si vous devez envoyer plusieurs requêtes HTTP différentes, une meilleure approche consiste à utiliser un seul composant requête HTTP et à le reconfigurer à l'exécution pour envoyer chaque requête.

Envoi d'une requête et gestion de sa réponse

Envoi d'une requête HTTP

Pour envoyer une requête HTTP, vous devez spécifier au moins les éléments suivants :

La méthode de requête HTTP détermine l'action que le serveur doit effectuer sur la ressource située à l'URL spécifiée. Cette action peut concerner l'envoi des données de la ressource ou la mise à jour de la ressource avec les données incluses dans votre requête.

La façon dont vous envoyez une requête HTTP au moyen d'un composant TNetHTTPRequest dépend de la méthode de requête HTTP que vous souhaitez utiliser.

Remarque: Les fonctions qui envoient une requête, Execute ou les fonctions spécifiques à une méthode, sont toutes bloquantes. Ainsi, ces fonctions ne se terminent pas tant qu'une réponse n'a pas été fournie par le serveur. Voir Suivi de la progression du téléchargement des données de la réponse ci-dessous.

Envoi d'une requête HTTP en utilisant les méthodes de requête HTTP DELETE, GET, HEAD, OPTIONS et TRACE

Les méthodes de requête HTTP suivantes ne nécessitent pas de données en entrée autres que l'URL de la ressource cible :

Pour envoyer une requête HTTP en utilisant l'une de ces méthodes de requête HTTP, configurez d'abord votre requête à la conception :

  1. Configurez la propriété URL avec l'URL de la ressource cible.
  2. Configurez la propriété MethodString avec le nom de la méthode de requête HTTP que vous souhaitez utiliser.
Remarque: Les noms des méthodes de requête HTTP sont sensibles à la casse.

Appelez ensuite Execute pour envoyer votre requête.

Envoi d'une requête HTTP en utilisant les méthodes de requête HTTP MERGE, PATCH et PUT

En plus de l'URL de la ressource cible, les méthodes de requête HTTP suivantes nécessitent des données en entrée :

Pour envoyer une requête HTTP en utilisant l'une de ces méthodes de requête HTTP, appelez sa fonction correspondante (voir le tableau ci-dessous). Dans votre appel, spécifiez l'URL de la ressource cible en premier argument et une instance de TStream en second argument.

Méthode de requête HTTP Fonction TNetHTTPRequest
PUT Put
PATCH Patch
MERGE Merge
PATCH via PUT* PatchAlternative
MERGE via PUT* MergeAlternative
* Certains proxies HTTP ne prennent pas en charge les dernières méthodes de requête HTTP standard (telles que PATCH) ou les méthodes de requête HTTP non standard (telles que MERGE). Dans ces cas, vous pouvez établir un proxy entre les méthodes de requête HTTP et une autre méthode de requête HTTP. Pour cela, la requête inclut des en-têtes qui spécifient la méthode de requête HTTP prévue.

Envoi d'une requête HTTP en utilisant la méthode de requête HTTP POST

En plus de l'URL de la ressource cible, la méthode de requête HTTP POST (EN) nécessite des données en entrée.

Pour envoyer une requête HTTP en utilisant la méthode de requête HTTP POST, appelez Post. Dans votre appel, vous devez spécifier l'URL de la ressource cible en premier argument. Les autres arguments dépendent de la façon dont vous souhaitez fournir les données d'entrée de votre requête :

  • Pour envoyer le contenu d'un fichier local, spécifiez le chemin local d'accès à ce fichier en second argument de votre appel.
  • Pour envoyer le contenu d'un flux, fournissez votre instance de TStream en second argument de votre appel.
  • Pour envoyer les données d'une fiche encodées en tant que message multi-partie MIME (EN) suivant le standard HTML 4 (EN), fournissez votre instance de TMultipartFormData en second argument de votre appel.
  • Pour envoyer le contenu d'une liste de chaînes, fournissez votre instance de TStrings en second argument de votre appel, et si vos chaînes ne sont pas encodées en UTF-8, fournissez une instance de TEncoding en quatrième argument. Par exemple :
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);

Gestion d'une réponse HTTP

Lorsque le serveur cible envoie une réponse à votre requête, l'événement OnRequestCompleted de votre composant requête HTTP se produit. Définissez un gestionnaire d'événement pour cet événement afin de lire les données provenant de la réponse du serveur. En cas d'erreur pendant votre requête, l'événement OnRequestError de votre composant requête HTTP se produit à la place.

Le gestionnaire d'événement de OnRequestCompleted reçoit deux paramètres :

  • Sender est votre composant requête HTTP.
  • AResponse est un objet qui implémente l'interface IHTTPResponse.

Vous pouvez obtenir toutes les données de la réponse à partir de AResponse :

Gestion des cookies

La propriété AllowCookies du composant client HTTP vous permet de spécifier si vous acceptez les cookies envoyés par le serveur dans la réponse. Si AllowCookies vaut True, le client HTTP enregistre les cookies reçus dans son CookieManager.

Remarque: Le client HTTP ajoute toujours ses cookies existants à la requête, quelle que soit la valeur de AllowCookies.

Gestion des redirections

Utilisez la propriété HandleRedirects pour contrôler la manière dont le composant client HTTP gère les redirections. La valeur par défaut vaut True, ce qui signifie que le composant client HTTP suit automatiquement les redirections.

Utilisez la propriété MaxRedirects du composant client HTTP pour spécifier le nombre maximal de redirections que le composant peut suivre. Si le composant client HTTP atteint le nombre maximal de redirections spécifié, il déclenche une exception de type ENetHTTPRequestException.

Gestion du téléchargement des données de réponse

Au fur et à mesure que votre client HTTP télécharge la réponse à votre requête, l'événement OnReceiveData de votre objet requête HTTP se produit. Fournissez un gestionnaire d'événement pour OnReceiveData afin de suivre la progression du téléchargement des données de la réponse. Votre gestionnaire d'événement reçoit les paramètres suivants :

  • Sender, qui est votre objet requête HTTP.
  • AContentLength, qui est la longueur attendue des données de la réponse en nombre d'octets.
  • AReadCount, qui est le nombre d'octets des données de la réponse que le client HTTP a téléchargé jusqu'ici.
  • Abort, qui est le paramètre booléen qui vous permet d'annuler le téléchargement.

Lorsque le téléchargement est terminé, OnReceiveData se produit pour la dernière fois, et les valeurs de AContentLength et AReadCount sont identiques. OnRequestCompleted se produit peu de temps après.

Suivi de la progression du téléchargement des données de la réponse

Pour suivre l'évolution du téléchargement des données, utilisez les valeurs de AContentLength et AReadCount dans le gestionnaire d'événement OnReceiveData. Voici un exemple qui calcule le pourcentage de données téléchargées :

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
    }
}

Annulation du téléchargement des données de réponse

Pour annuler le téléchargement des données de réponse, changez la valeur de Abort en True dans le gestionnaire d'événement OnReceiveData.

Envoi d'une requête avec des en-têtes personnalisés

Le composant client HTTP et le composant requête HTTP vous permettent tous deux de définir des en-têtes personnalisés. Les en-têtes personnalisés que vous pouvez spécifier sont les suivants :

Lorsque vous exécutez une requête, la méthode THTTPClient.Execute du framework HTTP combine les en-têtes personnalisés à partir du composant client HTTP et du composant requête HTTP correspondant, puis ajoute ces en-têtes à la requête finale.

Gestion des connexions sécurisées

Le composant client HTTP prend en charge les connexions (HTTPS) sécurisées. Le framework HTTP gère automatiquement les demandes de certificat émises et déclenche l'événement approprié si nécessaire :

Pour plus d'informations sur la gestion des certificats, voir les sections Gestion des certificats côté serveur et Gestion des certificats côté client.

Gestion de l'authentification et des certificats

Gestion de l'authentification d'accès de base HTTP

Lorsque vous envoyez une requête HTTP à un serveur qui requiert une authentification d'accès de base HTTP, l'événement OnAuthEvent de votre objet client HTTP se produit. Pour soumettre vos informations d'authentification d'accès, fournissez un gestionnaire pour cet événement, et si la valeur du deuxième paramètre que le gestionnaire d'événement reçoit (AnAuthTarget) est TAuthTargetType.Server, remplissez les variables AUserName et APassword avec votre nom d'utilisateur et mot de passe pour l'accès HTTP. Par exemple :

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";
    }
}

Votre gestionnaire d'événement reçoit également le domaine du serveur HTTP qui requiert une authentification (ARealm) et l'URL cible de votre requête (AURL).

Pour abandonner le processus d'authentification HTTP, définissez la valeur de AbortAuth sur True.

Envoi d'une requête derrière un proxy

Lorsque vous êtes derrière un proxy qui requiert une authentification, vous pouvez définir les paramètres proxy qui sont utilisés pour l'authentification. L'exemple suivant montre comment procéder :

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;

Pour spécifier les paramètres de proxy, vous avez aussi la possibilité de fournir une chaîne URL qui inclut les informations associées au proxy :

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

Sinon, vous pouvez spécifier les informations d'identification pour l'authentification proxy dans le gestionnaire d'événement OnAuthEvent. Consultez la section Gestion de l'authentification d'accès de base HTTP et vérifiez que la valeur de AnAuthTarget vaut TAuthTargetType.Proxy plutôt que TAuthTargetType.Server.

Gestion des paramètres proxy avec un client HTTP

Le tableau suivant explique la manière dont le client HTTP gère les paramètres proxy du système sur différentes plates-formes :

Plate-forme Comportement

Windows

Le client HTTP utilise les paramètres proxy du système. Vous pouvez ignorer les paramètres proxy du système et vous pouvez également fournir d'autres paramètres proxy pour le client HTTP. Pour ignorer les paramètres proxy du système, créez des paramètres proxy pour le client HTTP et spécifiez http://direct comme URL.

macOS

Le client HTTP utilise toujours les paramètres proxy du système. Même si vous fournissez d'autres paramètres proxy pour le client HTTP, celui-ci utilise les paramètres proxy du système.

iOS

Le client HTTP utilise toujours les paramètres proxy du système. Même si vous fournissez d'autres paramètres proxy pour le client HTTP, celui-ci utilise les paramètres proxy du système.

Android

Le client HTTP utilise les paramètres proxy du système. Vous ne pouvez pas ignorer ces paramètres, mais vous pouvez fournir d'autres paramètres proxy pour le client HTTP.

Linux

Le client HTTP utilise les paramètres proxy du système. Vous ne pouvez pas ignorer ces paramètres, mais vous pouvez fournir d'autres paramètres proxy pour le client HTTP.

Remarque: Si le système ne spécifie aucun paramètre proxy (la connexion est directe), cela est également considéré comme un "réglage". Par exemple, sur un système iOS ou macOS n'ayant aucun paramètre proxy défini, vous ne pouvez pas fournir de paramètres proxy pour le client HTTP. Les paramètres que vous fournissez sont ignorés car les paramètres système (réglage "aucun proxy") sont utilisés.
Attention: Jusqu'à RAD Studio 10.4, la bibliothèque client HTTP utilisait l'API NSURLConnection, qui a depuis été rendue obsolète par Apple sur Mac OS X 10.11 et iOS 9. RAD Studio10.4.1 prend en charge NSURLSession, une API plus récente, sur les deux plates-formes (elle résout également des problèmes liés à la prise en charge des proxies sur macOS).

Gestion du stockage des informations d'identification utilisateur

TNetHTTPClient vous permet de stocker les informations d'identification pour l'authentification HTTP ou proxy. Chaque information d'identification stockée peut contenir un nom d'utilisateur, un mot de passe, un type cible d'authentification, un domaine et une URL cible.

L'exemple suivant montre comment utiliser TNetHTTPClient.CredentialsStorage pour enregistrer des informations d'identification, puis les utiliser pour s'authentifier lors de la connexion à un serveur HTTP nécessitant une authentification de base :

  1. Créez des informations d'identification et ajoutez-les à votre stockage dédié :
    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. Utilisez les informations d'identification enregistrées. Par exemple, vous pouvez écrire un gestionnaire d'événement OnAuthEvent dans lequel vous pouvez :
    • Utiliser TCredentialsStorage.FindAccurateCredential pour rechercher des informations d'identification correspondant au type d'authentification nécessaire (TAuthTargetType.Server).
    • Utiliser le nom d'utilisateur et le mot de passe correspondant aux informations d'identification appropriées pour l'authentification.
    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;
}

Gestion des certificats côté serveur

Si le serveur fournit un certificat SSL non valide, l'événement OnValidateServerCertificate se produit. Fournissez un gestionnaire d'événement pour OnValidateServerCertificate afin de vérifier le certificat serveur (Certificate) et déterminer si vous acceptez ou non ce dernier. Si vous acceptez le certificat serveur, définissez la valeur du paramètre Accept sur True.

Gestion des certificats côté client

Si le serveur requiert un certificat client, l'événement OnNeedClientCertificate se produit. Fournissez un gestionnaire d'événement pour OnNeedClientCertificate afin de vérifier votre liste de certificats client (ACertificateList) et déterminer le certificat que vous souhaitez envoyer au serveur. Pour envoyer un certificat de la liste, définissez la valeur de AnIndex sur l'index du certificat cible dans ACertificateList.

Remarque: Si la méthode HTTP de la première requête à un serveur qui requiert un certificat côté client n'est ni HEAD ni GET (c'est donc POST), le code d'état de la réponse du serveur est 413. Envoyez toujours une requête HEAD ou GET en premier. L'utilisation d'une requête HEAD est généralement un meilleur choix, puisque moins de données sont transférées.

Rendre les requêtes asynchrones

Les requêtes sont synchrones par défaut. Pendant une requête, l'exécution de votre application s'arrête quand vous lancez votre requête, et reprend la main seulement quand vous obtenez une réponse du serveur ou quand la requête dépasse le délai d'attente.

Si vous voulez rendre vos requêtes asynchrones, afin que les requêtes n'arrêtent pas l'exécution de votre application, vous devez activer la propriété Asynchronous du composant client ou la propriété Asynchronous du composant requête, selon le composant utilisé pour effectuer votre requête.

Voir aussi

Récupérée de « https://docwiki.embarcadero.com/RADStudio/Alexandria/f/index.php?title=Utilisation_d%27un_client_HTTP&oldid=217536 »