Bietet Zugriff auf die Steam-Cloud-Dateien eines Steam-Benutzers. Dies ermöglicht hauptsächlich die plattformübergreifende Speicherung Ihres Spiels. Die Steam-Version Ihres Spiels kann die Steamworks-Cloud-Funktionen verwenden (entweder über die ISteamRemoteStorage-API oder die Steam Auto-Cloud). Nicht-Steam-Versionen können diese WebAPI verwenden, um auf die Dateien zuzugreifen und neue Versionen hochzuladen.

Ihr Spiel benötigt die Zugangsberechtigung vom Benutzer, um auf dessen Steam-Cloud-Dateien zugreifen zu können. Dies ist über OAuth möglich. Beachten Sie bitte, dass die Berechtigungen read_cloud und write_cloud erforderlich sind.

Weitere Informationen finden Sie auch in der allgemeinen Steam-Dokumentation WebAPI-Übersicht, insbesondere dem Abschnitt „Service-Schnittstellen“. GET-Anfragen können mit Parametern in der URL durchgeführt werden. Es ist allerdings für POST-Anfragen empfohlen, dass sich alle Parameter im Textkörper der Anfrage befinden. Der Parameter access-token ist direkt Form-kodiert und die übrigen Parameter sollten sich in einer JSON-Struktur befinden, die über das Feld input-json festgelegt werden können.

Antworten auf wohlgeformte und authentifizierte Anfragen sind üblicherweise 200 OK. Jedoch kann die Anfrage fehlschlagen: der detaillierte Steam-Fehlercode befindet sich in der Kopfzeile von x-eresult. Der Wert für „success“ ist 1. Alle übrigen Werte sind wahrscheinlich Fehler; weitere Details finden Sie in der Dokumentation für steam_api.h.

Aufzählung von Dateien

Benötigt OAuth-Zugriff auf read_cloud.

EnumerateUserFiles

Beispiel:

Name	Typ	Erforderlich?	Beschreibung
access_token	string	✔	OAuth-Zugriffstoken für den Benutzer
appid	uint32	✔	Ihre App-ID
extended_details	bool		Beinhaltet Details wie Download-Links für die Dateien
count	uint32		Die max. Anzahl der aufzuzählenden Dateien (Standardeinstellung: 500)
start_index	uint32		Anfangsindexnummer der aufzuzählenden Datei (Standardeinstellung: 0)

Zählt die Steam-Cloud-Dateien des Benutzers für Ihr Spiel auf. Beginnt mit einem „start_index“ von null und wird, wenn nötig, wiederholt, wenn der Benutzer mehr als „count“ Dateien hat.

Die Antwort hat 2 Felder:

Name	Typ	Beschreibung
files	siehe unten	Eine Liste von Dateidetails
total_files	uint32	Die Gesamtzahl der Dateien, die der Benutzer für Ihre Anwendung in der Steam Cloud hat.

Die Dateiliste enthält die folgenden Informationen:

Name	Typ	Beschreibung
appid	uint32	Dieselbe App-ID
ugcid	uint64	Einzigartige Datei-ID
filename	string	Der Dateiname
timestamp	uint64	Zeitpunkt der letzten Änderung an der Datei in Unixzeit
file_size	uint64	Die Dateigröße in Byte
url	string	Eine URL, die zum Herunterladen der Datei verwendet werden kann.
steamid_creator	uint64	Die Steam-ID des Benutzers
flags	uint64	Nur zur internen Verwendung durch Steam
platforms_to_sync	uint32	Liste der Plattformen, für die diese Datei gültig ist. Siehe Hochladen von Dateien für die Liste der möglichen Werte.
file_sha	string	Hex-String (40 Zeichen), die den SHA1-Digest der Datei repräsentiert.

Dateien herunterladen

Um eine Datei herunterzuladen, müssen Sie eine GET-Anfrage an die oben von EnumerateFiles zurückgegebene URL stellen.

Dateien bearbeiten

Benötigt OAuth-Zugriff auf write_cloud.

Die Bearbeitung von Dateien umfasst das Hochladen neuer Dateien und neuer Versionen bestehender Dateien sowie das Löschen von Dateien aus der Steam Cloud.

Eine Reihe von Änderungen an Dateien sollten in einen Batch gepackt werden. Batches werden zur Übermittlung einer Absicht für Ihren Satz an Änderungen an die Steam Cloud verwendet und helfen die Wahrscheinlichkeit von Dateikonflikten zu reduzieren.

Eine vollständige Batch-Sequenz sieht wie folgt aus:

• BeginAppUploadBatch-Aufruf, der die vorgesehenen Uploads und Löschungen aufführt.
  
• 0 oder mehr uploads unter Verwendung der folgenden Reihenfolge:
  
  • BeginHTTPUpload
    
  • HTTP-Operation PUT zum Hochladen der Datei
    
  • CommitHTTPUpload
• 0 oder mehr deletes (Löschungen) unter Verwendung von Delete
  
• CompleteAppUploadBatch

Hinweis: Sie müssen CompleteAppUploadBatch aufrufen, egal, ob alle Uploads und/oder Löschungen vollständig erfolgreich waren oder nicht. Failing to call CompleteAppUploadBatch will result in a time period of several minutes where new upload attempts for this user and app are blocked with a "too many pending requests" response.

BeginHTTPUpload

The first operation for a set of file modifications is to call BeginAppUploadBatch. This call communicates the set of intended uploads and deletes to the SteamCloud, as well as information about the user's machine which is doing the update.

Example:

Name	Typ	Erforderlich?	Beschreibung
access_token	string	✔	OAuth-Zugriffstoken für den Benutzer
appid	uint32	✔	Ihre App-ID
machine_name	string	✔	A name for the source machine, preferably one the user has applied to the device
files_to_upload	string list	✔	List of all files to be uploaded (new files or updates for existing files) as part of this batch.
files_to_delete	string list	✔	List of all files to be deleted from Steam Cloud as part of this batch.

Call this API to begin the upload batch.

Note that for list parameters, such as "files_to_upload", the syntax when used as a GET param is as follows:
In a JSON-encoded field in a POST param, it is as follows:

The response data:

Name	Typ	Beschreibung
batch_id	uint64	ID of this batch, to be used with the CompleteAppUploadBatch call
app_change_number	uint64	currently unused by this API

Your application must remember the batch_id from this response and submit it to the CompleteAppUploadBatch request once all uploads and deletes have been attempted.

CompleteAppUploadBatch

Once all uploads and deletes have been attempted, successful or not, you must call CompleteAppUploadBatch. This indicates to Steam that all operations for this batch have been attempted and it will then allow any newly-requested batches immediately.

Example:

Name	Typ	Required	Description
access_token	string	✔	OAuth access token for the user
appid	uint32	Der Header-Wert	Your App ID
batch_id	uint64	✔	The ID number of this batch
batch_eresult	uint32	✔	Result of the batch (see remarks)

The batch_eresult parameter should be either 1 (success) or 2 (failure). Technically this is an EResult value (see steam_api.h for the list). Indicating success or failure to Steam is sufficient for this method.

There's no body data in the response from this API.

BeginHTTPUpload

Uploading is done via a two-part API. You'll first call BeginHTTPUpload to get details on where to upload the file, then when that is complete, call CommitHTTPUpload.

Example:

Name	Typ	Erforderlich?	Beschreibung
access_token	string	✔	OAuth-Zugriffstoken für den Benutzer
appid	uint32	✔	Ihre App-ID
file_size	uint32	✔	size of the file in bytes
filename	string	✔	Der Dateiname
file_sha	uint32	✔	Hex-String (40 Zeichen), die den SHA1-Digest der Datei repräsentiert.
platforms_to_sync	string	✔	List of platforms for which this file is valid. Possible values: All, Windows, MacOS, linux, Android, iPhoneOS, Switch. Case-insensitive.
upload_batch_id	uint64	✔	The batch_id returned by BeginAppUploadBatch above

Call this API to initiate uploading a new file (or new version of an existing file) to Steam Cloud for the user. New versions of existing files will overwrite the existing version.

Note that for list parameters, such as "platforms_to_sync", the syntax when used as a GET param is as follows:
In a JSON-encoded field in a POST param, it is as follows:

The response data:

Name	Typ	Description
access_token	uint64	unique file id (not needed)
timestamp	uint32	epoch timestamp for this change
url_host	bool	Host FQDN you will upload the file to
url_path	string	path for request. Note that currently this includes a leading slash character (/) already.
use_https	bool	set to true if you must use HTTPS to perform the upload (generally always true)
request_headers	see below	list of HTTP headers you must set on the subsequent PUT request

The "request_headers" list contains this data:

Name	Type	Description
name	string	the header name
value	string	the header value

To upload the file, make a PUT request to https://<url_host><url_path>, where each of the above specified HTTP headers has the specified value. On success you may receive a 200 OK, 201 Created, or 204 No Content response, depending on the storage provider.

This request may look like:

When that completes (whether a success or a failure), call:

CommitHTTPUpload

Example:

Name	Type	Required	Description
access_token	string	✔	OAuth access token for the user
appid	uint32	✔	Your App ID
transfer_succeeded	bool	✔	true if the PUT request succeeded
filename	string	✔	the file name
file_sha	string	✔	Hex string (40 digits) representing the SHA1 digest of the file.

The response to this API currently has a single field, "file_committed", which will be true if Steam was able to fully commit the change. If false, then the upload has failed -- a new file was not recorded, and if it was an update to an existing file, the existing file still exists and will be returned by future Enumerate/Download requests.

Delete

Example:

Name	Type	Required	Description
access_token	string	✔	OAuth access token for the user
appid	uint32	✔	Your App ID
filename	string	✔	filename of the file to delete

This API will delete the specified file from the user's Steam Cloud. Deleting files is permanent; no prior versions of the file are retained. There's no body data in the response from this API.