Class: ClientRequest

Class: ClientRequest

Создает HTTP/HTTPS-запросы.

Process: Main, Utility
This class is not exported from the 'electron' module. Он доступен только в качестве возвращаемого значения других методов в Electron API.

ClientRequest реализует интерфейс Writable Stream и EventEmitter.

new ClientRequest(options)

• options (Object | string) - If options is a string, it is interpreted as the request URL. Если это объект, ожидается полное указание HTTP запроса через следующие свойства:
  • method string (опционально) - Метод HTTP-запроса. По умолчанию метод GET.
  • url string (опционально) - URL запроса. Необходимо предоставить в абсолютной форме с протокольной схемой, указанной как http или https.
  • headers Record<string, string | string[]> (optional) - Headers to be sent with the request.
  • session Session (optional) - The Session instance with which the request is associated.
  • partition string (optional) - The name of the partition with which the request is associated. По умолчанию является пустой строкой. The session option supersedes partition. Поэтому, если параметр session явно указан, то partition игнорируется.
  • credentials string (optional) - Can be include, omit or same-origin. Whether to send credentials with this request. If set to include, credentials from the session associated with the request will be used. If set to omit, credentials will not be sent with the request (and the 'login' event will not be triggered in the event of a 401). If set to same-origin, origin must also be specified. This matches the behavior of the fetch option of the same name. If this option is not specified, authentication data from the session will be sent, and cookies will not be sent (unless useSessionCookies is set).
  • useSessionCookies boolean (optional) - Whether to send cookies with this request from the provided session. If credentials is specified, this option has no effect. По умолчанию - false.
  • protocol string (опционально) - Может быть http: или https:. The protocol scheme in the form 'scheme:'. По умолчанию 'http:'.
  • host string (опционально) - объединенное с номером порта доменное имя сервера 'доменное_имя:порт'.
  • hostname string (опционально) – доменное имя сервера.
  • port Integer (опционально) – номер порта сервера.
  • path string (опционально) - часть пути запроса URL.
  • redirect string (необязательный) - Позиция иконки, может иметь значения follow, error или manual. The redirect mode for this request. When mode is error, any redirection will be aborted. When mode is manual the redirection will be cancelled unless request.followRedirect is invoked synchronously during the redirect event. По умолчанию - follow.
  • origin string (optional) - The origin URL of the request.
  • 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.
  • cache string (optional) - can be default, no-store, reload, no-cache, force-cache or only-if-cached.
  • priority string (optional) - can be throttled, idle, lowest, low, medium, or highest. По умолчанию idle.
  • priorityIncremental boolean (optional) - the incremental loading flag as part of HTTP extensible priorities (RFC 9218). По умолчанию - true.

Свойства options, такие как protocol, host, hostname, port и path, строго следуют модели Node.js, которая описана в модуле URL.

Например, мы могли бы создать такой же запрос на 'github.com' следующим образом:

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

События экземпляра

Событие: 'response'

Возвращает:

• response IncomingMessage - An object representing the HTTP response message.

Событие: 'login'

Возвращает:

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

Происходит, когда прокси-сервер, выполняющий проверку подлинности, запрашивает учетные данные пользователя.

Ожидается, что функция 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.

Событие: 'abort'

Возникает при прерывании request. Событие abort не будет запущено, если request уже закрыт.

Событие: 'error'

Возвращает:

• error Error - объект ошибки, содержащий некоторую информацию о неудаче.

Происходит, когда модулю net не удается выполнить сетевой запрос. Обычно, когда объект request генерирует событие error, в последствии последует событие close и не будет представлен объект ответа.

Событие: 'close'

Происходит как последнее событие в транзакции HTTP запроса-ответа. Событие close указывает, что больше события не будут происходить ни на request, ни на response объектах.

Событие: 'redirect'

Возвращает:

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

Используется при возврате сервером перенаправленного ответа (например, 301 Перемещено навсегда). Вызов request.followRedirect продолжится с перенаправлением. Если событие обработано, request.followRedirect должен вызываться синхронно, в противном случае запрос будет отменен.

Свойства экземпляра

request.chunkedEncoding

boolean, определяющий, будет ли запрос использовать в HTTP шифрование передачи частей или нет. По умолчанию - false. Свойство доступно для чтения и записи, в любом случае оно может быть установлено только до первой операции записи, поскольку HTTP-заголовки еще не отправлены. Попытка установить свойство chunkedEncoding после первой записи вызовет ошибку.

Использование шифрование частей настоятельно рекомендуется, если Вам необходимо отправить большое содержимое запроса как данные, которые будут передаваться в потоке малыми частями вместо внутренней буферизации в памяти процесса Electron.

Методы экземпляра

request.setHeader(name, value)

• name string - имя дополнительного HTTP-заголовка.
• value string - значение дополнительного HTTP-заголовка.

Добавляет дополнительный HTTP-заголовок. Имя заголовка будет выдано как есть, без нижнего регистра. Может быть вызвано только перед первой записи. Вызов этого метода после первой записи вызовет ошибку. Если переданное значение это не string, тогда метод toString() будет вызван, чтобы получить конечное значение.

Certain headers are restricted from being set by apps. These headers are listed below. More information on restricted headers can be found in Chromium's header utils.

• Content-Length
• Host
• Trailer or Te
• Обновить
• Cookie2
• Keep-Alive
• Transfer-Encoding

Additionally, setting the Connection header to the value upgrade is also disallowed.

request.getHeader(name)

• name string - укажите имя дополнительного заголовка.

Возвращает string - значение ранее установленного дополнительного заголовка.

request.removeHeader(name)

• name string - укажите имя дополнительного заголовка.

Удаляет ранее установленное дополнительное имя заголовка. Этот метод может быть вызван только перед первой записью. Попытка вызвать его после первой записи приведет к ошибке.

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

• chunk (string | Buffer) - Часть данных в теле запроса. Если это строка, то она преобразуется в буфер в заданной кодировке.
• encoding string (опционально) - используется для конвертирования строковые части в объект Buffer. По умолчанию 'utf-8'.
• callback Function (опционально) - вызывается после того, как закончится операция записи.

callback является по существу фиктивной функцией, представленной в целях сохранения схожести с API Node.JS. Вызывается асинхронно в следующем такте, после содержимое chunk будет отправлено в сетевой слой Chromium. В отличие от реализации Node.JS, не гарантировано, что содержимое chunk будет отправлено до вызова callback.

Добавляет часть данных в содержимое запроса. Первая операция записи может привести тому, что заголовки запроса будут отправлены. После первой операции записи, недопустимо добавлять или удалять пользовательские заголовки.

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

• chunk (string | Buffer) (опционально)
• encoding string (опционально)
• callback Function (опционально)

Возвращает this.

Отправляет последний фрагмент данных запроса. Последующие операции по записи или завершению не будут разрешены. Событие finish происходит сразу после завершения операции.

request.abort()

Отменяет текущую транзакцию HTTP. Если запрос уже сгенерировал событие close, операция прерывания не будет иметь эффекта. Иначе текущее событие будет генерировать события abort и close. Кроме того, если есть текущий объект ответа, будет сгенерировано событие aborted.

request.followRedirect()

Continues any pending redirection. Can only be called during a 'redirect' event.

request.getUploadProgress()

Возвращает Object:

• active boolean - Активен ли запрос в данный момент. Если это false, никакие другие свойства не будут установлены
• started boolean - Началась ли загрузка. Если это false, то и current и total будут установлены в 0.
• current Integer - количество байтов, которые были загружены
• total Integer - количество байтов, которые будут загружены в этом запросе

Вы можете использовать этот метод в сочетании с запросами POST, чтобы получить прогресс загрузки файла или другой передачи данных.