mirror of
https://github.com/godotengine/godot-docs-l10n.git
synced 2026-01-05 14:10:19 +03:00
cf78697eea
Currently including `zh_CN` and `es` which both have very high completion ratios. Others will be added once they reach a significant percentage too. These RST files will be used by godot-docs in place of its `classes` folder after we sync with https://github.com/godotengine/godot-docs/pull/5458. The update workflow is manual for now (example for `zh_CN`): - Build `godotengine/godot` in the branch we currently track (now `3.x`) - Run `godot --doctool -l zh_CN` - Run `cd doc && make rst LANGARG=zh_CN` - Copy `doc/_build/rst/*` to `classes/zh_CN/` here - Make sure to have `classes/zh_CN/index.rst` copied from `docs/classes`
377 lines
22 KiB
ReStructuredText
377 lines
22 KiB
ReStructuredText
:github_url: hide
|
|
|
|
.. Generated automatically by doc/tools/make_rst.py in Godot's source tree.
|
|
.. DO NOT EDIT THIS FILE, but the HTTPRequest.xml source instead.
|
|
.. The source is found in doc/classes or modules/<name>/doc_classes.
|
|
|
|
.. _class_HTTPRequest:
|
|
|
|
HTTPRequest
|
|
===========
|
|
|
|
**Inherits:** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
|
|
|
|
Un nodo con la capacidad de enviar peticiones HTTP(S).
|
|
|
|
Descripción
|
|
----------------------
|
|
|
|
A node with the ability to send HTTP requests. Uses :ref:`HTTPClient<class_HTTPClient>` internally.
|
|
|
|
Can be used to make HTTP requests, i.e. download or upload files or web content via HTTP.
|
|
|
|
\ **Warning:** See the notes and warnings on :ref:`HTTPClient<class_HTTPClient>` for limitations, especially regarding SSL security.
|
|
|
|
\ **Example of contacting a REST API and printing one of its returned fields:**\
|
|
|
|
::
|
|
|
|
func _ready():
|
|
# Create an HTTP request node and connect its completion signal.
|
|
var http_request = HTTPRequest.new()
|
|
add_child(http_request)
|
|
http_request.connect("request_completed", self, "_http_request_completed")
|
|
|
|
# Perform a GET request. The URL below returns JSON as of writing.
|
|
var error = http_request.request("https://httpbin.org/get")
|
|
if error != OK:
|
|
push_error("An error occurred in the HTTP request.")
|
|
|
|
# Perform a POST request. The URL below returns JSON as of writing.
|
|
# Note: Don't make simultaneous requests using a single HTTPRequest node.
|
|
# The snippet below is provided for reference only.
|
|
var body = {"name": "Godette"}
|
|
error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body)
|
|
if error != OK:
|
|
push_error("An error occurred in the HTTP request.")
|
|
|
|
|
|
# Called when the HTTP request is completed.
|
|
func _http_request_completed(result, response_code, headers, body):
|
|
var response = parse_json(body.get_string_from_utf8())
|
|
|
|
# Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org).
|
|
print(response.headers["User-Agent"])
|
|
|
|
\ **Example of loading and displaying an image using HTTPRequest:**\
|
|
|
|
::
|
|
|
|
func _ready():
|
|
# Create an HTTP request node and connect its completion signal.
|
|
var http_request = HTTPRequest.new()
|
|
add_child(http_request)
|
|
http_request.connect("request_completed", self, "_http_request_completed")
|
|
|
|
# Perform the HTTP request. The URL below returns a PNG image as of writing.
|
|
var error = http_request.request("https://via.placeholder.com/512")
|
|
if error != OK:
|
|
push_error("An error occurred in the HTTP request.")
|
|
|
|
|
|
# Called when the HTTP request is completed.
|
|
func _http_request_completed(result, response_code, headers, body):
|
|
var image = Image.new()
|
|
var error = image.load_png_from_buffer(body)
|
|
if error != OK:
|
|
push_error("Couldn't load the image.")
|
|
|
|
var texture = ImageTexture.new()
|
|
texture.create_from_image(image)
|
|
|
|
# Display the image in a TextureRect node.
|
|
var texture_rect = TextureRect.new()
|
|
add_child(texture_rect)
|
|
texture_rect.texture = texture
|
|
|
|
Tutoriales
|
|
--------------------
|
|
|
|
- :doc:`../tutorials/networking/http_request_class`
|
|
|
|
- :doc:`../tutorials/networking/ssl_certificates`
|
|
|
|
Propiedades
|
|
----------------------
|
|
|
|
+-----------------------------+----------------------------------------------------------------------------+-----------+
|
|
| :ref:`int<class_int>` | :ref:`body_size_limit<class_HTTPRequest_property_body_size_limit>` | ``-1`` |
|
|
+-----------------------------+----------------------------------------------------------------------------+-----------+
|
|
| :ref:`int<class_int>` | :ref:`download_chunk_size<class_HTTPRequest_property_download_chunk_size>` | ``65536`` |
|
|
+-----------------------------+----------------------------------------------------------------------------+-----------+
|
|
| :ref:`String<class_String>` | :ref:`download_file<class_HTTPRequest_property_download_file>` | ``""`` |
|
|
+-----------------------------+----------------------------------------------------------------------------+-----------+
|
|
| :ref:`int<class_int>` | :ref:`max_redirects<class_HTTPRequest_property_max_redirects>` | ``8`` |
|
|
+-----------------------------+----------------------------------------------------------------------------+-----------+
|
|
| :ref:`int<class_int>` | :ref:`timeout<class_HTTPRequest_property_timeout>` | ``0`` |
|
|
+-----------------------------+----------------------------------------------------------------------------+-----------+
|
|
| :ref:`bool<class_bool>` | :ref:`use_threads<class_HTTPRequest_property_use_threads>` | ``false`` |
|
|
+-----------------------------+----------------------------------------------------------------------------+-----------+
|
|
|
|
Métodos
|
|
--------------
|
|
|
|
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| void | :ref:`cancel_request<class_HTTPRequest_method_cancel_request>` **(** **)** |
|
|
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`get_body_size<class_HTTPRequest_method_get_body_size>` **(** **)** |const| |
|
|
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`get_downloaded_bytes<class_HTTPRequest_method_get_downloaded_bytes>` **(** **)** |const| |
|
|
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Status<enum_HTTPClient_Status>` | :ref:`get_http_client_status<class_HTTPRequest_method_get_http_client_status>` **(** **)** |const| |
|
|
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`request<class_HTTPRequest_method_request>` **(** :ref:`String<class_String>` url, :ref:`PoolStringArray<class_PoolStringArray>` custom_headers=PoolStringArray( ), :ref:`bool<class_bool>` ssl_validate_domain=true, :ref:`Method<enum_HTTPClient_Method>` method=0, :ref:`String<class_String>` request_data="" **)** |
|
|
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`request_raw<class_HTTPRequest_method_request_raw>` **(** :ref:`String<class_String>` url, :ref:`PoolStringArray<class_PoolStringArray>` custom_headers=PoolStringArray( ), :ref:`bool<class_bool>` ssl_validate_domain=true, :ref:`Method<enum_HTTPClient_Method>` method=0, :ref:`PoolByteArray<class_PoolByteArray>` request_data_raw=PoolByteArray( ) **)** |
|
|
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| void | :ref:`set_http_proxy<class_HTTPRequest_method_set_http_proxy>` **(** :ref:`String<class_String>` host, :ref:`int<class_int>` port **)** |
|
|
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| void | :ref:`set_https_proxy<class_HTTPRequest_method_set_https_proxy>` **(** :ref:`String<class_String>` host, :ref:`int<class_int>` port **)** |
|
|
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
|
|
Señales
|
|
--------------
|
|
|
|
.. _class_HTTPRequest_signal_request_completed:
|
|
|
|
- **request_completed** **(** :ref:`int<class_int>` result, :ref:`int<class_int>` response_code, :ref:`PoolStringArray<class_PoolStringArray>` headers, :ref:`PoolByteArray<class_PoolByteArray>` body **)**
|
|
|
|
Emitido cuando se completa una solicitud.
|
|
|
|
Enumeraciones
|
|
--------------------------
|
|
|
|
.. _enum_HTTPRequest_Result:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_SUCCESS:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_CHUNKED_BODY_SIZE_MISMATCH:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_CANT_CONNECT:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_CANT_RESOLVE:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_CONNECTION_ERROR:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_SSL_HANDSHAKE_ERROR:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_NO_RESPONSE:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_BODY_SIZE_LIMIT_EXCEEDED:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_REQUEST_FAILED:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_DOWNLOAD_FILE_CANT_OPEN:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_DOWNLOAD_FILE_WRITE_ERROR:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_REDIRECT_LIMIT_REACHED:
|
|
|
|
.. _class_HTTPRequest_constant_RESULT_TIMEOUT:
|
|
|
|
enum **Result**:
|
|
|
|
- **RESULT_SUCCESS** = **0** --- Solicitud con éxito.
|
|
|
|
- **RESULT_CHUNKED_BODY_SIZE_MISMATCH** = **1**
|
|
|
|
- **RESULT_CANT_CONNECT** = **2** --- La solicitud falló mientras se conectaba.
|
|
|
|
- **RESULT_CANT_RESOLVE** = **3** --- La solicitud falló al resolverse.
|
|
|
|
- **RESULT_CONNECTION_ERROR** = **4** --- La solicitud falló debido a un error de conexión (lectura/escritura).
|
|
|
|
- **RESULT_SSL_HANDSHAKE_ERROR** = **5** --- La solicitud falló en el handshake del SSL.
|
|
|
|
- **RESULT_NO_RESPONSE** = **6** --- La solicitud no tiene respuesta (todavía).
|
|
|
|
- **RESULT_BODY_SIZE_LIMIT_EXCEEDED** = **7** --- La solicitud excedió su límite de tamaño máximo, ver :ref:`body_size_limit<class_HTTPRequest_property_body_size_limit>`.
|
|
|
|
- **RESULT_REQUEST_FAILED** = **8** --- Solicitud fallida (actualmente no utilizada).
|
|
|
|
- **RESULT_DOWNLOAD_FILE_CANT_OPEN** = **9** --- HTTPRequest no pudo abrir el archivo descargado.
|
|
|
|
- **RESULT_DOWNLOAD_FILE_WRITE_ERROR** = **10** --- HTTPRequest no pudo escribir el archivo descargado.
|
|
|
|
- **RESULT_REDIRECT_LIMIT_REACHED** = **11** --- La solicitud alcanzó su límite máximo de redireccionamiento, ver :ref:`max_redirects<class_HTTPRequest_property_max_redirects>`.
|
|
|
|
- **RESULT_TIMEOUT** = **12**
|
|
|
|
Descripciones de Propiedades
|
|
--------------------------------------------------------
|
|
|
|
.. _class_HTTPRequest_property_body_size_limit:
|
|
|
|
- :ref:`int<class_int>` **body_size_limit**
|
|
|
|
+-----------+----------------------------+
|
|
| *Default* | ``-1`` |
|
|
+-----------+----------------------------+
|
|
| *Setter* | set_body_size_limit(value) |
|
|
+-----------+----------------------------+
|
|
| *Getter* | get_body_size_limit() |
|
|
+-----------+----------------------------+
|
|
|
|
Tamaño máximo permitido para los cuerpos de la respuesta.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_property_download_chunk_size:
|
|
|
|
- :ref:`int<class_int>` **download_chunk_size**
|
|
|
|
+-----------+--------------------------------+
|
|
| *Default* | ``65536`` |
|
|
+-----------+--------------------------------+
|
|
| *Setter* | set_download_chunk_size(value) |
|
|
+-----------+--------------------------------+
|
|
| *Getter* | get_download_chunk_size() |
|
|
+-----------+--------------------------------+
|
|
|
|
The size of the buffer used and maximum bytes to read per iteration. See :ref:`HTTPClient.read_chunk_size<class_HTTPClient_property_read_chunk_size>`.
|
|
|
|
Set this to a lower value (e.g. 4096 for 4 KiB) when downloading small files to decrease memory usage at the cost of download speeds.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_property_download_file:
|
|
|
|
- :ref:`String<class_String>` **download_file**
|
|
|
|
+-----------+--------------------------+
|
|
| *Default* | ``""`` |
|
|
+-----------+--------------------------+
|
|
| *Setter* | set_download_file(value) |
|
|
+-----------+--------------------------+
|
|
| *Getter* | get_download_file() |
|
|
+-----------+--------------------------+
|
|
|
|
El archivo para descargar. dará salida a cualquier archivo recibido en él.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_property_max_redirects:
|
|
|
|
- :ref:`int<class_int>` **max_redirects**
|
|
|
|
+-----------+--------------------------+
|
|
| *Default* | ``8`` |
|
|
+-----------+--------------------------+
|
|
| *Setter* | set_max_redirects(value) |
|
|
+-----------+--------------------------+
|
|
| *Getter* | get_max_redirects() |
|
|
+-----------+--------------------------+
|
|
|
|
Número máximo de redirecciones permitidas.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_property_timeout:
|
|
|
|
- :ref:`int<class_int>` **timeout**
|
|
|
|
+-----------+--------------------+
|
|
| *Default* | ``0`` |
|
|
+-----------+--------------------+
|
|
| *Setter* | set_timeout(value) |
|
|
+-----------+--------------------+
|
|
| *Getter* | get_timeout() |
|
|
+-----------+--------------------+
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_property_use_threads:
|
|
|
|
- :ref:`bool<class_bool>` **use_threads**
|
|
|
|
+-----------+------------------------+
|
|
| *Default* | ``false`` |
|
|
+-----------+------------------------+
|
|
| *Setter* | set_use_threads(value) |
|
|
+-----------+------------------------+
|
|
| *Getter* | is_using_threads() |
|
|
+-----------+------------------------+
|
|
|
|
Si ``true``, se utiliza el multihilo para mejorar el rendimiento.
|
|
|
|
Descripciones de Métodos
|
|
------------------------------------------------
|
|
|
|
.. _class_HTTPRequest_method_cancel_request:
|
|
|
|
- void **cancel_request** **(** **)**
|
|
|
|
Cancela la solicitud actual.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_method_get_body_size:
|
|
|
|
- :ref:`int<class_int>` **get_body_size** **(** **)** |const|
|
|
|
|
Devuelve la longitud del cuerpo de respuesta.
|
|
|
|
\ **Nota:** Algunos servidores web pueden no enviar la longitud del cuerpo. En este caso, el valor devuelto será ``-1``. Si se utiliza la codificación de transferencia de trozos, la longitud del cuerpo también será ``-1``.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_method_get_downloaded_bytes:
|
|
|
|
- :ref:`int<class_int>` **get_downloaded_bytes** **(** **)** |const|
|
|
|
|
Devuelve la cantidad de bytes que esta HTTPRequest ha descargado.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_method_get_http_client_status:
|
|
|
|
- :ref:`Status<enum_HTTPClient_Status>` **get_http_client_status** **(** **)** |const|
|
|
|
|
Devuelve el estado actual del :ref:`HTTPClient<class_HTTPClient>` subyacente. Véase :ref:`Status<enum_HTTPClient_Status>`.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_method_request:
|
|
|
|
- :ref:`Error<enum_@GlobalScope_Error>` **request** **(** :ref:`String<class_String>` url, :ref:`PoolStringArray<class_PoolStringArray>` custom_headers=PoolStringArray( ), :ref:`bool<class_bool>` ssl_validate_domain=true, :ref:`Method<enum_HTTPClient_Method>` method=0, :ref:`String<class_String>` request_data="" **)**
|
|
|
|
Creates request on the underlying :ref:`HTTPClient<class_HTTPClient>`. If there is no configuration errors, it tries to connect using :ref:`HTTPClient.connect_to_host<class_HTTPClient_method_connect_to_host>` and passes parameters onto :ref:`HTTPClient.request<class_HTTPClient_method_request>`.
|
|
|
|
Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` if request is successfully created. (Does not imply that the server has responded), :ref:`@GlobalScope.ERR_UNCONFIGURED<class_@GlobalScope_constant_ERR_UNCONFIGURED>` if not in the tree, :ref:`@GlobalScope.ERR_BUSY<class_@GlobalScope_constant_ERR_BUSY>` if still processing previous request, :ref:`@GlobalScope.ERR_INVALID_PARAMETER<class_@GlobalScope_constant_ERR_INVALID_PARAMETER>` if given string is not a valid URL format, or :ref:`@GlobalScope.ERR_CANT_CONNECT<class_@GlobalScope_constant_ERR_CANT_CONNECT>` if not using thread and the :ref:`HTTPClient<class_HTTPClient>` cannot connect to host.
|
|
|
|
\ **Note:** When ``method`` is :ref:`HTTPClient.METHOD_GET<class_HTTPClient_constant_METHOD_GET>`, the payload sent via ``request_data`` might be ignored by the server or even cause the server to reject the request (check `RFC 7231 section 4.3.1 <https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.1>`__ for more details). As a workaround, you can send data as a query string in the URL. See :ref:`String.http_escape<class_String_method_http_escape>` for an example.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_method_request_raw:
|
|
|
|
- :ref:`Error<enum_@GlobalScope_Error>` **request_raw** **(** :ref:`String<class_String>` url, :ref:`PoolStringArray<class_PoolStringArray>` custom_headers=PoolStringArray( ), :ref:`bool<class_bool>` ssl_validate_domain=true, :ref:`Method<enum_HTTPClient_Method>` method=0, :ref:`PoolByteArray<class_PoolByteArray>` request_data_raw=PoolByteArray( ) **)**
|
|
|
|
Creates request on the underlying :ref:`HTTPClient<class_HTTPClient>` using a raw array of bytes for the request body. If there is no configuration errors, it tries to connect using :ref:`HTTPClient.connect_to_host<class_HTTPClient_method_connect_to_host>` and passes parameters onto :ref:`HTTPClient.request<class_HTTPClient_method_request>`.
|
|
|
|
Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` if request is successfully created. (Does not imply that the server has responded), :ref:`@GlobalScope.ERR_UNCONFIGURED<class_@GlobalScope_constant_ERR_UNCONFIGURED>` if not in the tree, :ref:`@GlobalScope.ERR_BUSY<class_@GlobalScope_constant_ERR_BUSY>` if still processing previous request, :ref:`@GlobalScope.ERR_INVALID_PARAMETER<class_@GlobalScope_constant_ERR_INVALID_PARAMETER>` if given string is not a valid URL format, or :ref:`@GlobalScope.ERR_CANT_CONNECT<class_@GlobalScope_constant_ERR_CANT_CONNECT>` if not using thread and the :ref:`HTTPClient<class_HTTPClient>` cannot connect to host.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_method_set_http_proxy:
|
|
|
|
- void **set_http_proxy** **(** :ref:`String<class_String>` host, :ref:`int<class_int>` port **)**
|
|
|
|
Sets the proxy server for HTTP requests.
|
|
|
|
The proxy server is unset if ``host`` is empty or ``port`` is -1.
|
|
|
|
----
|
|
|
|
.. _class_HTTPRequest_method_set_https_proxy:
|
|
|
|
- void **set_https_proxy** **(** :ref:`String<class_String>` host, :ref:`int<class_int>` port **)**
|
|
|
|
Sets the proxy server for HTTPS requests.
|
|
|
|
The proxy server is unset if ``host`` is empty or ``port`` is -1.
|
|
|
|
.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
|
|
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
|
|
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
|