Proporciona acceso a los archivos de Steam Cloud de un usuario de Steam. Esto está destinado principalmente a permitir el guardado multiplataforma para tu juego. La versión de Steam del juego puede utilizar características del Cloud de Steamworks (ya sea la API ISteamRemoteStorage o Steam Auto-Cloud). Las versiones que no son de Steam pueden utilizar esta WebAPI para acceder a los archivos y subir nuevas versiones.

Tu juego necesita conseguir permiso del usuario para acceder a sus archivos en Steam Cloud. Esto se puede hacerse a través de OAuth. Lo más probable es que quieras solicitar tanto el permiso read_cloud como el permiso write_cloud.

Consulta también nuestro artículo Descripción general de la WebAPI, concretamente la sección titulada "Interfaces de servicio". Pueden hacerse solicitudes GET con parámetros en el URL; sin embargo, para las solicitudes POST se recomienda que todos los parámetros estén en el cuerpo de la solicitud. El parámetro access-token está directamente codificado en el formulario, y el resto de los parámetros deberían estar en una estructura JSON configurada a través del campo input-json.

La respuesta a las solicitudes bien formadas y autenticadas suele ser 200 OK. Sin embargo, la solicitud puede haber fallado. Encontrarás el código de error detallado de Steam en el encabezado x-eresult. El valor para "success" es 1. Cualquier otro valor probablemente sea un error. Para más información, consulta la documentación sobre steam_api.h.

Enumeración de archivos

Requiere acceso OAuth read_cloud.

EnumerateUserFiles

Ejemplo:

Nombre	Tipo	Obligatorio	Descripción
access_token	string	✔	Token de acceso OAuth del usuario
appid	uint32	✔	El id. de tu aplicación
extended_details	bool		Incluye detalles como los enlaces de descarga de los archivos
count	uint32		Número máximo de archivos para enumerar (por defecto, 500)
start_index	uint32		Iniciando el índice de archivos para enumerar (valor predeterminado 0)

Enumera los archivos de Steam Cloud del usuario para tu juego. Comienza con un "start_index" de cero, y repite en caso necesario si el usuario tiene más de "count" archivos.

La respuesta tiene dos campos:

Nombre	Tipo	Descripción
files	ver más abajo	Una lista con los detalles de los archivos
total_files	uint32	El número total de archivos que el usuario tiene en Steam Cloud para tu aplicación

La lista de archivos contiene estos datos:

Nombre	Tipo	Descripción
appid	uint32	Mismo id. de aplicación
ugcid	uint64	Id. de archivo único
nombre de archivo	string	Nombre del archivo
timestamp	uint64	Tiempo Unix en que se modificó el archivo por última vez
file_size	uint32	Tamaño del archivo en bytes
url	string	Un URL que se puede utilizar para descargar el archivo
steamid_creator	uint64	Id. de Steam del usuario
flags	uint32	Solo para uso interno de Steam
platforms_to_sync	string	Lista de plataformas para las que este archivo es válido. Ver Carga de archivos para obtener la lista de posibles valores
file_sha	string	Cadena hexadecimal (40 dígitos) que representa el resumen SHA1 del archivo

Descarga de archivos

Para descargar un archivo, simplemente haz una solicitud GET al URL devuelto por EnumerateUserFiles.

Modificación de archivos

Requiere acceso OAuth write_cloud.

Modificar archivos incluye cargar archivos nuevos, cargar nuevas versiones de los archivos existentes y borrar archivos de Steam Cloud.

El set de acciones de modificación de archivos se debe consolidar en un batch. Los batches se usan para comunicar la intención del conjunto de tus modificaciones a la Steam Cloud, lo cual ayuda a reducir la probabilidad de conflictos entre archivos.

Una secuencia de lotes completa tendrá este aspecto:

• Llamada a la función BeginAppUploadBatch, con una lista de lo que se carga y lo que se borra.
  
• 0 o más cargas, utilizando la secuencia:
  
  • BeginHTTPUpload.
    
  • Operación HTTP PUT para cargar el archivo.
    
  • CommitHTTPUpload.
• 0 o más borrados, utilizando Delete.
  
• CompleteAppUploadBatch

Hay que tener en cuenta que se debe llamar a CompleteAppUploadBatch independientemente de que las cargas y/o los borrados se lleven a cabo con éxito. Si no se llama a la función CompleteAppUploadBatch habrá un periodo de tiempo de varios minutos en el que los nuevos intentos de carga del usuario y de la aplicación quedarán bloqueados
y recibirán el mensaje "demasiadas solicitudes pendientes".

BeginAppUploadBatch

La primera operación para un conjunto de modificaciones de archivo es llamar a la función BeginAppUploadBatch. Esta llamada le comunica a Steam Cloud el conjunto de cargas y borrados previstos, así como la información sobre la máquina del usuario que está haciendo la actualización.

Ejemplo:

Nombre	Tipo	Obligatorio	Descripción
access_token	string	✔	Token de acceso OAuth del usuario
appid	uint32	✔	El id. de tu aplicación
machine_name	string	✔	Un nombre para la máquina de origen, preferiblemente uno que el usuario haya aplicado al dispositivo
files_to_upload	string list	✔	Lista de todos los archivos que se van a subir como parte de este lote, ya sean archivos nuevos o actualizaciones de archivos existentes
files_to_delete	string list	✔	Cadena hexadecimal (40 dígitos) que representa el resumen SHA1 del archivo.

Llama a esta API para iniciar la carga del lote.

Ten en cuenta que para los parámetros de la lista, como "files_to_upload", la sintaxis cuando se usa como un parámetro GET es la siguiente:
En un campo codificado en JSON en un parámetro POST, sería:

Los datos de la respuesta:

Nombre	Tipo	Descripción
batch_id	uint64	El id. de este batch, que se utilizará con la llamada CompleteAppUploadBatch.
app_change_number	uint64	Actualmente no utilizado por esta API.

Tu aplicación debe recordar el batch_id de esta respuesta e incluirlo en la petición de CompleteAppUploadBatch, una vez que se hayan intentado realizar todas las cargas y borrados.

CompleteAppUploadBatch

Una vez que se hayan intentado realizar todas las cargas y borrados, ya sea con o sin éxito, debes llamar a la función CompleteAppUploadBatch. Esto le indica a Steam que se han intentado realizar todas las operaciones de este lote, y entonces permitirá procesar inmediatamente cualquier otro lote recién pedido.

Ejemplo:

Nombre	Tipo	Obligatorio	Descripción
access_token	string	✔	OAuth es el token de acceso para el usuario.
appid	uint32	✔	El id. de tu aplicación.
batch_id	uint64	✔	El número de identificación de este batch.
batch_eresult	uint32	✔	Resultado del batch (ver comentarios).

El parámetro batch_eresult tiene que ser bien 1 (correcto) o 2 (incorrecto). Técnicamente este es un valor EResult (ver steam_api.h con la lista). Para este método es bastante con indicarle a Steam si fue correcto o no.

No hay datos en la respuesta de esta API.

BeginHTTPUpload

La carga se realiza a través de una API de dos partes. Primero llamarás a BeginHTTPUpload para obtener los detalles sobre dónde cargar el archivo y, cuando eso se haya completado, llamarás a CommitHTTPUpload.

Por ejemplo:

Nombre	Tipo	Obligatorio	Descripción
access_token	string	✔	OAuth es el token de acceso para el usuario
appid	uint32	✔	El id. de tu aplicación
file_size	uint32	✔	True si la solicitud PUT se ejecutó correctamente.
filename	string	✔	El nombre del archivo
file_sha	string	✔	Cadena hexadecimal (40 dígitos) que representa el resumen SHA1 del archivo
platforms_to_sync	string	✔	Lista de plataformas para las que este archivo es válido Valores posibles: All, Windows, macOS, Linux, Android, iPhoneOS, Switch. No distingue entre mayúsculas y minúsculas
upload_batch_id	uint64	✔	El batch_id devuelto por BeginAppUplaodBatch arriba.

Llama a esta API para iniciar la carga de un nuevo archivo (o una nueva versión de un archivo existente) a Steam Cloud para el usuario. Las nuevas versiones de los archivos existentes sobrescribirán la versión actual.

Ten en cuenta que para los parámetros de la lista, como "platforms_to_sync", la sintaxis cuando se usa como un parámetro GET es la siguiente:
En un campo codificado en JSON en un parámetro POST, sería:

Los datos de la respuesta:

Nombre	Tipo	Descripción
ugcid	uint64	Id. de archivo único (no es necesario)
timestamp	uint32	Marca de tiempo en formato epoch para este cambio
url_host	string	FQDN del host al que cargarás el archivo
url_path	string	Ruta de solicitud. Ten en cuenta que actualmente esto ya incluye una barra diagonal (/) al principio
use_https	bool	Se establece como "true" si debes usar HTTPS para realizar la carga (generalmente siempre es "true").
request_headers	ver más abajo	Lista de encabezados HTTP que debes establecer en la solicitud PUT posterior.

La lista "request_headers" contiene estos datos:

Nombre	Tipo	Descripción
name	string	El nombre del encabezado.
value	string	El valor del encabezado.

Para cargar el archivo, realiza una solicitud PUT a https://<url_host><url_path>/ donde cada uno de los encabezados HTTP indicados arriba tenga el valor especificado. En caso de éxito, puedes recibir una respuesta de 200 OK, 201 Created o 204 No Content, dependiendo del proveedor de almacenamiento.

La solicitud puede tener este aspecto:

Cuando se completa (correctamente o no), llama a:

CommitHTTPUpload

Por ejemplo:

Nombre	Tipo	Obligatorio	Descripción
access_token	string	✔	Token de acceso OAuth del usuario.
appid	uint32	✔	El id. de tu aplicación.
transfer_succeeded	bool	✔	True si la solicitud PUT tuvo éxito.
filename	string	✔	El nombre del archivo.
file_sha	string	✔	Cadena hexadecimal (40 dígitos) que representa el resumen SHA1 del archivo

La respuesta a esta API actualmente tiene un solo campo, "file_committed", que será true si Steam pudo completar el cambio. Si es "false", entonces la carga ha fallado: no se ha registrado ningún archivo nuevo o, si se trataba de la actualización de un archivo existente, el archivo original sigue existiendo y será devuelto por futuras solicitudes de enumeración o descarga.

Delete

Por ejemplo:

Nombre	Tipo	Obligatorio	Descripción
access_token	string	✔	Token de acceso OAuth del usuario.
appid	uint32	✔	El id. de tu aplicación.
filename	string	✔	Nombre del archivo que se quiere eliminar.

Esta API eliminará el archivo especificado del Steam Cloud del usuario. La eliminación es permanente; no se conservan versiones anteriores del archivo. No hay datos en la respuesta de esta API.