クラス: ClientRequest

HTTP/HTTPSリクエストを行います。

プロセス: メイン、ユーティリティ
このクラスは`'electron'`モジュールからエクスポートされません。Electron APIの他のメソッドの戻り値としてのみ使用できます。

ClientRequestはWritable Streamインターフェースを実装しており、そのためEventEmitterです。

`new ClientRequest(options)`

options (Object | string) - optionsが文字列の場合、リクエストURLとして解釈されます。オブジェクトの場合、次のプロパティを介してHTTPリクエストを完全に指定することが期待されます。
- method string (オプション) - HTTPリクエストメソッド。デフォルトはGETメソッドです。
- url string (オプション) - リクエストURL。プロトコルスキーム（httpまたはhttps）を指定した絶対形式で指定する必要があります。
- headers Record<string, string | string[]> (オプション) - リクエストと共に送信されるヘッダー。
- session Session (オプション) - リクエストに関連付けられているSessionインスタンス。
- partition string (オプション) - リクエストに関連付けられているpartitionの名前。デフォルトは空文字列です。sessionオプションはpartitionを優先します。そのため、sessionが明示的に指定されている場合、partitionは無視されます。
- credentials string (オプション) - include、omit、またはsame-originのいずれか。このリクエストにcredentialsを送信するかどうか。includeに設定すると、リクエストに関連付けられたセッションのcredentialsが使用されます。omitに設定すると、credentialsはリクエストと共に送信されません（401の場合、'login'イベントはトリガーされません）。same-originに設定する場合は、originも指定する必要があります。これは、同名のfetchオプションの動作と一致します。このオプションが指定されていない場合、セッションの認証データが送信され、Cookieは送信されません（useSessionCookiesが設定されている場合を除く）。
- useSessionCookies boolean (オプション) - 指定されたセッションからこのリクエストにCookieを送信するかどうか。credentialsが指定されている場合、このオプションは効果がありません。デフォルトはfalseです。
- protocol string (オプション) - http:またはhttps:のいずれか。'scheme:'形式のプロトコルスキーム。デフォルトは'http:'です。
- host string (オプション) - ホスト名とポート番号を連結したサーバーホスト'hostname:port'.
- hostname string (オプション) - サーバーホスト名。
- port Integer (オプション) - サーバーのリッスンポート番号。
- path string (オプション) - リクエストURLのパス部分。
- redirect string (オプション) - follow、error、またはmanualのいずれか。このリクエストのリダイレクトモード。モードがerrorの場合、リダイレクトはすべて中止されます。redirectイベント中にrequest.followRedirectが同期的に呼び出されない限り、モードがmanualの場合、リダイレクトはキャンセルされます。デフォルトはfollowです。
- origin string (オプション) - リクエストのオリジンURL。
- referrerPolicy string (オプション) - ""、no-referrer、no-referrer-when-downgrade、origin、origin-when-cross-origin、unsafe-url、same-origin、strict-origin、またはstrict-origin-when-cross-originのいずれか。デフォルトはstrict-origin-when-cross-originです。
- cache string (オプション) - default、no-store、reload、no-cache、force-cache、またはonly-if-cachedのいずれか。

protocol、host、hostname、port、pathなどのoptionsプロパティは、URLモジュールで説明されているように、Node.jsモデルに厳密に従います。

たとえば、'github.com'への同じリクエストを次のように作成できます。

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

インスタンスイベント

イベント: 'response'

戻り値

response IncomingMessage - HTTPレスポンスメッセージを表すオブジェクト。

戻り値

authInfo Object
- isProxy boolean
- scheme string
- host string
- port Integer
- realm string
callback Function
- username string (オプション)
- password string (オプション)

認証プロキシがユーザー資格情報を要求している場合に発生します。

callback関数は、ユーザー資格情報を用いてコールバックされることが期待されます。

username string
password string

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

空の資格情報を提供すると、リクエストはキャンセルされ、レスポンスオブジェクトに認証エラーが報告されます。

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

イベント: 'finish'

requestのデータの最後のチャンクがrequestオブジェクトに書き込まれた直後に発生します。

イベント: 'abort'

requestが中断された場合に発生します。requestが既に閉じている場合は、abortイベントは発生しません。

イベント: 'error'

戻り値

error Error - 失敗に関する情報を提供するエラーオブジェクト。

netモジュールがネットワークリクエストの発行に失敗した場合に発生します。通常、requestオブジェクトがerrorイベントを発生させると、その後closeイベントが発生し、レスポンスオブジェクトは提供されません。

イベント: 'close'

HTTPリクエストとレスポンスのトランザクションの最後のイベントとして発生します。closeイベントは、requestまたはresponseオブジェクトでそれ以上のイベントが発生しないことを示します。

イベント: 'redirect'

戻り値

statusCode Integer
method string
redirectUrl string
responseHeaders Record<string, string[]>

サーバーがリダイレクトレスポンス（例：301 Moved Permanently）を返した場合に発生します。request.followRedirectを呼び出すと、リダイレクトが続行されます。このイベントが処理された場合、request.followRedirectを**同期的に**呼び出す必要があります。そうでない場合、リクエストはキャンセルされます。

インスタンスプロパティ

`request.chunkedEncoding`

リクエストがHTTPチャンク転送エンコーディングを使用するかどうかを指定するboolean値。デフォルトはfalseです。このプロパティは読み取り可能で書き込み可能ですが、HTTPヘッダーはまだワイヤー上にないため、最初の書き込み操作の前にのみ設定できます。最初の書き込み後にchunkedEncodingプロパティを設定しようとすると、エラーが発生します。

大量のリクエストボディを送信する必要がある場合は、チャンクエンコーディングを使用することを強くお勧めします。データはElectronプロセスのメモリ内で内部的にバッファリングされるのではなく、小さなチャンクでストリーミングされます。

インスタンスメソッド

`request.setHeader(name, value)`

name string - 追加のHTTPヘッダー名。
value string - 追加のHTTPヘッダー値。

追加のHTTPヘッダーを追加します。ヘッダー名は小文字に変換せずにそのまま発行されます。最初の書き込みの前にのみ呼び出すことができます。最初の書き込み後にこのメソッドを呼び出すと、エラーが発生します。渡された値がstringでない場合、そのtoString()メソッドが呼び出されて最終的な値が取得されます。

アプリによる設定が制限されているヘッダーがあります。これらのヘッダーは以下にリストされています。制限されたヘッダーの詳細については、Chromiumのヘッダーユーティリティを参照してください。

Content-Length
Host
TrailerまたはTe
Upgrade
Cookie2
Keep-Alive
転送エンコーディング

さらに、Connectionヘッダーをupgradeに設定することも許可されていません。

`request.getHeader(name)`

name 文字列 - 追加のヘッダー名を指定します。

戻り値 string - 以前設定された追加ヘッダーの値。

`request.removeHeader(name)`

name 文字列 - 追加のヘッダー名を指定します。

以前設定された追加ヘッダーを削除します。このメソッドは、最初の書き込みの前にのみ呼び出すことができます。最初の書き込み後に呼び出すと、エラーが発生します。

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

chunk (文字列 | Buffer) - リクエストボディのデータのチャンク。文字列の場合、指定されたエンコーディングを使用してBufferに変換されます。
encoding 文字列 (オプション) - 文字列チャンクをBufferオブジェクトに変換するために使用されます。デフォルトは'utf-8'です。
callback 関数 (オプション) - 書き込み操作が終了した後に呼び出されます。

callbackは、本質的にNode.js APIとの類似性を維持するために導入されたダミー関数です。chunkの内容がChromiumネットワーク層に配信された後、次のティックで非同期的に呼び出されます。Node.jsの実装とは異なり、callbackが呼び出される前にchunkの内容がワイヤーにフラッシュされる保証はありません。

リクエストボディにデータチャンクを追加します。最初の書き込み操作によって、リクエストヘッダーがワイヤー上に発行される可能性があります。最初の書き込み操作後、カスタムヘッダーを追加または削除することはできません。

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

chunk (文字列 | Buffer) (オプション)
encoding 文字列 (オプション)
callback 関数 (オプション)

戻り値 this。

リクエストデータの最後のチャンクを送信します。その後、書き込みまたは終了操作は許可されません。finishイベントは、終了操作の直後に発生します。

`request.abort()`

進行中のHTTPトランザクションをキャンセルします。リクエストがすでにcloseイベントを発生させている場合、中止操作は効果がありません。それ以外の場合は、進行中のイベントがabortおよびcloseイベントを発生させます。さらに、進行中のレスポンスオブジェクトがある場合は、abortedイベントが発生します。

`request.followRedirect()`

保留中のリダイレクトを続行します。'redirect'イベント中にのみ呼び出すことができます。

`request.getUploadProgress()`

戻り値 Object

active ブール値 - リクエストが現在アクティブかどうか。これがfalseの場合、他のプロパティは設定されません。
started ブール値 - アップロードが開始されたかどうか。これがfalseの場合、currentとtotalの両方が0に設定されます。
current 整数 - これまでにアップロードされたバイト数。
total 整数 - このリクエストでアップロードされるバイト数。

このメソッドは、POSTリクエストと組み合わせて、ファイルアップロードまたはその他のデータ転送の進捗状況を取得するために使用できます。