Classe : ClientRequest

Classe : ClientRequest

Faire des requêtes HTTP/HTTPS.

Processus : Main, Utility
Cette classe n’est pas exportée à partir du module 'electron'. Elle n'est disponible qu'en tant que valeur de retour des autres méthodes dans l'API Electron.

ClientRequest implémente l'interface de Writable Stream et, du coup, elle est un EventEmitter.

new ClientRequest(options)

• options (Object | string) - Si options est une string, elle sera interpretée comme l'URL de la requête. Si par contre il s'agit d'un objet, on devra complètement spécifier une requête HTTP via les propriétés suivantes :
  • method string (facultatif) - La méthode de requête HTTP. Méthode GET par défaut.
  • url string (facultatif) - L'URL de la requête. Doit être fourni sous la forme absolue avec le schéma de protocole spécifié en http ou https.
  • headers Record<string, string | string[]> (optional) - Headers to be sent with the request.
  • session Session (facultatif) - instance de Session associée à la requête.
  • partition string (facultatif) - Le nom de la partition avec laquelle la requête est associée. Par défaut, la chaîne vide est utilisée. L'option session l'emporte sur partition. Ainsi, si une session est explicitement spécifiée , partition est ignorée.
  • credentials string (optional) - Can be include, omit or same-origin. Whether to send credentials with this request. Si la valeur est à include, les informations d'identification de la session associée seront utilisées. Si par contre la valeur est à omit, les identifiants ne seront pas envoyés avec la requête (et l'événement 'login' ne sera pas déclenché dans le cas d'un code d'erreur 401). If set to same-origin, origin must also be specified. Cela correspond au comportement de l’option du même nom de fetch. Si cette option n’est pas spécifiée, les données d’authentification de la session seront envoyées et les cookies eux, ne seront pas envoyés (sauf si useSessionCookies est défini).
  • useSessionCookies boolean (facultatif) - Indique les cookies doivent être envoyés avec cette requête depuis la session fournie. Si credentials est spécifié, cette option n'a aucun effet. Par défaut la valeur est false.
  • protocol string (facultatif) -Peut être http: ou https:. Le schéma du protocole sous la forme 'scheme:'. La valeur par défaut est 'http:'.
  • host string (facultatif) - L'hôte du serveur fourni en concaténation de le nom d'hôte et le numéro de port 'hostname:port'.
  • hostname string (facultatif) - Le nom d'hôte du serveur.
  • port Integer (facultatif) - Le numéro de port d'écoute du serveur.
  • path string (facultatif) - La partie chemin de l'URL de la requête.
  • redirect string (facultatif) -Peut être follow, error ou manual. Mode de redirection pour cette requête. Lorsque le mode est error, toute redirection sera abandonnée. Lorsque le mode est manual , la redirection est annulée, sauf si request.followRedirect est appelée pendant l’événement redirect. Valeur par défaut, follow.
  • origin string (facultatif) - L'URL d'origine de la requête.
  • referrerPolicy string (optional) - can be "", no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, unsafe-url, same-origin, strict-origin, or strict-origin-when-cross-origin. strict-origin-when-cross-origin par défaut.
  • cache string (optional) - can be default, no-store, reload, no-cache, force-cache or only-if-cached.

options propriétés telles que protocole, host, hostname, port et path suivent strictement le modèle Node.js comme décrit dans le module URL.

Par exemple, nous aurions pu créer la même requête à 'github.com' comme suit:

const request = net.request({
  method: 'GET',
  protocol: 'https:',
  hostname: 'github.com',
  port: 443,
  path: '/'
})

Événements d’instance

Événement : 'response'

Retourne :

• response IncomingMessage - Un objet représentant le message de réponse HTTP.

Événement : 'login'

Retourne :

• Objet authInfo
  • isProxy boolean
  • scheme string
  • host string
  • port Integer
  • realm string
• callback Function
  • username string (facultatif)
  • password string (facultatif)

Émis lorsqu'un proxy d'authentification demande les identifiants de l'utilisateur.

La fonction callback est censée être rappelée avec les identifiants de l'utilisateur :

• username string
• password string

request.on('login', (authInfo, callback) => {
  callback('username', 'password')
})

Fournir des identifiants vides annulera la demande et signalera une erreur d'authentification sur l'objet de réponse :

request.on('response', (response) => {
  console.log(`STATUS: ${response.statusCode}`)
  response.on('error', (error) => {
    console.log(`ERROR: ${JSON.stringify(error)}`)
  })
})
request.on('login', (authInfo, callback) => {
  callback()
})

Événement : 'finish'

Émis juste après le dernier chunk de l'objet request a été écrit dans l'objet request.

Événement : 'abort'

Émis lorsque la request est clôturée. L'événement abort ne sera pas déclenché si la request est déjà clôturée.

Événement : 'error'

Retourne :

• error Erreur - un objet d'erreur fournissant des informations sur l'échec.

Émis lorsque le module net ne parvient pas à émettre une requête réseau. Généralement lorsque l'objet request émet un événement error, un événement close sera ensuite suivi et aucun objet de réponse ne sera fourni.

Événement : 'close'

Émis en tant que dernier événement dans la transaction de réponse de requête HTTP. L'événement close indique qu'aucun événement ne sera émis sur les objets request ou response.

Événement : 'redirect'

Retourne :

• statusCode Integer
• method string
• redirectUrl string
• Enregistrement responseHeaders<string, string[]>

Émis lorsque le serveur renvoie une réponse de redirection (par exemple 301 Déplacé de manière permanente). Appeler request.followRedirect va continuer avec la redirection. Si cet événement est géré, request.followRedirect doit être appelé synchrones, sinon la requête sera annulée.

Propriétés d'instance

request.chunkedEncoding

boolean spécifie si la requête utilisera l'encodage de transfert HTTP chunked 'permettant le trasfert par bloc) ou non. false par défaut. La propriété est lisible et en écriture, Cependant, il ne peut être défini que avant la première opération d'écriture car les en-têtes HTTP ne sont pas encore mis sur le fil. Tenter de définir la propriété chunkedEncoding après la première écriture lancera une erreur.

L'utilisation de l'encodage chunked est fortement recommandée si vous avez besoin d'envoyer un grand corps de requête car les données seront diffusées en petits morceaux au lieu d'être en mémoire tampon interne dans la mémoire de processus d'Electron.

Méthodes d’instance

request.setHeader(name, value)

• name string - Un nom d'en-tête HTTP supplémentaire.
• valeur string - Une valeur d'en-tête HTTP supplémentaire.

Ajoute un en-tête HTTP supplémentaire. Le nom de l'en-tête sera publié tel quel sans minuscules. Il peut être appelé seulement avant d'écrire en premier. Appeler cette méthode après la première écriture lancera une erreur. Si la valeur passée n'est pas une string, sa méthode toString() sera appelée pour obtenir la valeur finale.

Certains en-têtes ne peuvent pas être définis par les applications. Ces en-têtes sont répertoriés ci-dessous. Vous trouverez plus d’informations sur les en-têtes restreints dans Chromium's header utils.

• Content-Length
• Host
• Trailer or Te
• Upgrade
• Cookie2
• Keep-Alive
• Transfer-Encoding

De plus, la définition de l'en-tête Connection à la valeur upgrade est également interdite.

request.getHeader(name)

• name chaîne - Spécifie un nom d'en-tête supplémentaire.

Retourne string - La valeur d'un nom d'en-tête supplémentaire précédemment défini.

request.removeHeader(name)

• name chaîne - Spécifie un nom d'en-tête supplémentaire.

Supprime un nom d’en-tête supplémentaire précédemment défini. Cette méthode ne peut être appelée qu’avant la première écriture. Toute tentative d'’appel après la première écriture générera une erreur.

request.write(chunk[, encoding][, callback])

• chunk (string | Buffer) - Fragment de données du corps de la requête. S'il s'agit d'une string , elle est convertie en Buffer en utilisant l'encodage spécifié.
• encoding string (facultatif) - Utilisé pour convertir des fragments de chaîne en objets Buffer. La valeur par défaut est 'utf-8'.
• callback Fonction (facultatif) - Appelée après la fin de l'opération d'écriture.

callback est essentiellement une fonction factice introduite dans le but de conserver la similarité avec l'API Node.js. Il est appelé de manière asynchrone dans le prochain tick après que le contenu chunk ait été livré à la couche de réseau Chromium. Contrairement à l'implémentation de Node.js, il n'est pas garanti que le contenu chunk ait été vidé sur le fil avant que callback ne soit appelé.

Ajoute un fragment de données au corps de la requête. La première opération d'écriture peut causer la publication des en-têtes de la requête sur le fil. Après la première opération d'écriture, il n'est pas autorisé d'ajouter ou de supprimer un en-tête personnalisé.

request.end([chunk][, encoding][, callback])

• chunk (string | Buffer) (facultatif)
• encoding string (facultatif)
• callback Function (facultatif)

Retourne this.

Envoie le dernier bloc des données de la demande. Les opérations ultérieures d’écriture ou de fin ne seront pas autorisées. L’événement finish est émis juste après l’opération finale.

request.abort()

Annule une transaction HTTP en cours. Si la requête a déjà émis l'événement close , l'opération d'abandon n'aura aucun effet. Sinon, un événement en cours émettra des événements abandon et close . De plus, s'il y a un objet de réponse en cours, il émettra l'évènement abandonné.

request.followRedirect()

Poursuit toute redirection en attente. Ne peut être appelé que pendant un événement 'redirect' .

request.getUploadProgress()

Retourne Object:

• active booléen - Indique si la requête est actuellement active. Si c'est faux aucune autre propriété ne sera définie
• started booléen - Indique si le téléchargement a commencé. Si la valeur est false, current et total seront mis à 0.
• current Integer - Le nombre d'octets qui ont été téléchargés jusqu'à présent
• total Integer - Le nombre d'octets qui seront chargés dans cette requête

Vous pouvez utiliser cette méthode en conjonction avec les requêtes POST pour obtenir la progression d'un téléchargement de fichier ou d'un autre transfert de données.