Permet d'accéder aux fichiers Steam Cloud d'un compte Steam. Cela vous permet d'utiliser des sauvegardes multiplateformes pour votre jeu. La version Steam du jeu peut tirer parti des fonctionnalités du cloud Steamworks (soit via l'API ISteamRemoteStorage soit via Steam Auto-Cloud). Les versions non Steam peuvent utiliser la fonction WebAPI pour accéder aux fichiers et charger de nouvelles versions.
Il sera nécessaire d'obtenir l'autorisation de l'utilisateur ou l'utilisatrice pour accéder aux fichiers Steam Cloud. Pour ce faire, utilisez
OAuth. Il est conseillé de demander à la fois l'autorisation
read_cloud et
write_cloud.
Veuillez consulter la documentation générale relative à l'
API Web, notamment la section intitulée « Interfaces de service ». Les requêtes GET peuvent être exécutées avec les paramètres contenus dans l'URL. Il est cependant recommandé de garder tous les paramètres dans le corps de la requête pour les requêtes POST. Le paramètre
access-token est directement encodé dans le formulaire. Les paramètres restants doivent suivre une structure JSON via le champ
input-json.
La réponse aux requêtes bien formées et authentifiées sera généralement
200 OK. Il est cependant possible que la requête échoue. Le code d'erreur Steam détaillé se trouvera alors dans l'entête
x-eresult. La valeur pour « success » est 1. Toutes les autres valeurs seront certainement des erreurs. Pour plus d'informations, consultez la documentation relative à
steam_api.h.
Énumération des fichiers
Nécessite un accès OAuth
read_cloud.
EnumerateUserFiles
Exemple
GET https://api.steampowered.com/ICloudService/EnumerateUserFiles/v1/?access_token=<token>&appid=1234&extended_details=1 HTTP/1.1
Host: api.steampowered.com
Content-Length: 0
| Nom | Type | Requis | Description |
|---|
| access_token | string | ✔ | Jeton d'accès OAuth pour le compte. |
| appid | uint32 | ✔ | Votre AppID. |
| extended_details | bool | | Contient des informations telles que les liens vers les fichiers. |
| count | uint32 | | Nombre maximal de fichiers à énumérer (valeur par défaut = 500). |
| start_index | uint32 | | Premier index de fichier à énumérer (valeur par défaut = 0). |
Liste les fichiers sauvegardés sur Steam Cloud d'un compte pour votre jeu. Commence avec un « start_index » de zéro, puis itère si le compte possède plus de « count » fichiers le cas échéant.
La réponse a deux champs.
| Nom | Type | Description |
|---|
| files | voir ci-dessous | Liste d'informations relatives aux fichiers. |
| total_files | uint32 | Le nombre total de fichiers possédés par un compte sur Steam Cloud pour votre application. |
La liste des fichiers contient les données suivantes.
| Nom | Type | Description |
|---|
| appid | uint32 | AppID de l'application. |
| ugcid | uint64 | ID unique du fichier. |
| filename | string | Nom du fichier. |
| timestamp | uint64 | Horodatage de la dernière modification du fichier au format horaire Unix. |
| file_size | uint32 | Taille du fichier en octets. |
| url | string | URL de téléchargement du fichier. |
| steamid_creator | uint64 | SteamID du compte. |
| flags | uint32 | Utilisé uniquement en interne dans Steam. |
| platforms_to_sync | string | Liste de plateformes pour lesquelles ce fichier est valide. Consultez la section « Envoi des fichiers » pour connaitre la liste des valeurs possibles. |
| file_sha | string | Chaine de caractères hexadécimale (40 chiffres) représentant la synthèse SHA1 du fichier. |
Téléchargement de fichiers
Pour télécharger un fichier, effectuez une simple requête GET vers l'URL renvoyée par EnumerateUserFiles ci-dessus.
Modification de fichiers
Nécessite un accès OAuth à
write_cloud.
Télécharger de nouveaux fichiers ou de nouvelles versions de fichiers existants, ou encore supprimer des fichiers de Steam Cloud : toutes ces actions sont considérées comme des modifications des fichiers.
Tout ensemble de modifications de fichiers devrait être assemblé dans un lot
Batch. Ces lots servent à transmettre une intention à Steam Cloud pour votre ensemble de modifications, et ainsi réduire les possibilités de conflits entre fichiers.
Une séquence de lot entière ressemblera à cela :
- Appelle
BeginAppUploadBatch, dans le but d'obtenir la liste des chargements et suppressions prévues.
- 0 ou plus uploads, en utilisant la séquence suivante.
-
BeginHTTPUpload
- Opération HTTP
PUT pour charger le fichier.
-
CommitHTTPUpload
- 0 ou plus deletes, en utilisant
Delete.
-
CompleteAppUploadBatch
Veuillez noter que vous devez appeler
CompleteAppUploadBatch que les chargements ou suppressions de fichiers se soient bien déroulés ou non. Si
CompleteAppUploadBatch n'est pas appelé, cela provoquera un délai de plusieurs minutes pendant lequel la réponse « too many pending requests » (trop de requêtes en cours) sera renvoyée à chaque nouvelle tentative de chargement de fichiers par ce compte.
BeginAppUploadBatch
La première opération à effectuer au sein d'un ensemble de modifications de fichier est d'appeler
BeginAppUploadBatch. Cet appel transmet l'ensemble souhaité de chargements et de suppressions à Steam Cloud, ainsi que les données de l'ordinateur qui applique la mise à jour.
Exemple
POST https://api.steampowered.com/ICloudService/BeginAppUploadBatch/v1/ HTTP/1.1
Host: api.steampowered.com
Content-Type: application/x-www-form-urlencoded
Content-Length: <body length>
access_token=<token>&input_json={ "appid": "1234", "machine_name": "My%20Handheld", "files_to_upload": ["%25WinAppDataLocal%25Foobar%2FGamename%2Fcloud%2Fgames%2Fsave.sav"], "files_to_delete": ["%25WinAppDataLocal%25Foobar%2FGamename%2Fcloud%2Fgames%2Fsave_old.sav"] }
| Nom | Type | Requis | Description |
|---|
| access_token | string | ✔ | Jeton d'accès OAuth du compte. |
| appid | uint32 | ✔ | Votre AppID. |
| machine_name | string | ✔ | Nom pour l'ordinateur source, de préférence celui choisi par l'utilisateur ou l'utilisatrice. |
| files_to_upload | string list | ✔ | Liste de tous les fichiers à charger (nouveaux fichiers ou mises à jour de fichiers existants) faisant partie de ce lot. |
| files_to_delete | string list | ✔ | Liste de tous les fichiers faisant partie de ce lot à supprimer de Steam Cloud. |
Appelle cette API pour commencer le chargement du lot.
Veuillez noter que pour les paramètres de liste, comme « files_to_upload », lorsqu'utilisés comme paramètres GET, la syntaxe se présente comme suit.
&files_to_upload[0]=file1.sav&files_to_upload[1]=file2.sav
Dans un champ codé en JSON contenu dans un paramètre POST, elle se présente ainsi :
"files_to_upload": ["file1.sav", "file2.sav"]
Données de la réponse :
| Nom | Type | Description |
|---|
| batch_id | uint64 | ID de ce lot, à utiliser avec l'appel CompleteAppUploadBatch. |
| app_change_number | uint64 | Actuellement inutilisé par cette API. |
Votre application doit enregistrer
batch_id (ID du lot) depuis la réponse et le soumettre à la requête
CompleteAppUploadBatch une fois que tous les chargements et suppressions ont été tentés.
CompleteAppUploadBatch
Une fois que tous les chargements et suppressions ont été tentés, qu'ils aient été exécutés avec succès ou non, vous devez appeler
CompleteAppUploadBatch. Cela indique à Steam que toutes les opérations de ce lot ont été tentées et autorise alors immédiatement tout nouveau lot demandé.
Exemple
POST https://api.steampowered.com/ICloudService/CompleteAppUploadBatch/v1/ HTTP/1.1
Host: api.steampowered.com
Content-Type: application/x-www-form-urlencoded
Content-Length: <body length>
access_token=<token>&input_json={ "appid": "1234", "batch_id": "434565457423", "batch_eresult": "1" }
| Nom | Type | Requis | Description |
|---|
| access_token | string | ✔ | Jeton d'accès OAuth du compte. |
| appid | uint32 | ✔ | Votre AppID. |
| batch_id | uint64 | ✔ | ID de ce lot. |
| batch_eresult | uint32 | ✔ | Résultat du lot (voir notes). |
Le paramètre
batch_eresult devrait être soit 1 (succès) ou 2 (échec). Il s'agit techniquement d'une valeur
EResult (voir
steam_api.h pour la liste). Déclarer son succès ou son échec à Steam est suffisant pour cette méthode.
Il n'y a aucune donnée dans le corps de réponse de cette API.
BeginHTTPUpload
Le chargement s'effectue via une API en deux parties. BeginHTTPUpload est d'abord appelé pour obtenir les informations de destination du fichier à charger, puis, une fois cela effectué, CommitHTTPUpload est appelé.
Exemple
POST https://api.steampowered.com/ICloudService/BeginHTTPUpload/v1/ HTTP/1.1
Host: api.steampowered.com
Content-Type: application/x-www-form-urlencoded
Content-Length: <body length>
access_token=<token>&input_json={ "appid": "1234", "file_size": "7448889", "filename": "%25WinAppDataLocal%25Foobar%2FGamename%2Fcloud%2Fgames%2Fsave.sav", "file_sha": "FDFE308499263F9361B472648E9F49DC0B8799C8", "is_public": "0", "platforms_to_sync": ["all"], "upload_batch_id": "434565457423", }
| Nom | Type | Requis | Description |
|---|
| access_token | string | ✔ | Jeton d'accès OAuth du compte. |
| appid | uint32 | ✔ | Votre AppID. |
| file_size | uint32 | ✔ | Taille du fichier en octets. |
| filename | string | ✔ | Nom du fichier. |
| file_sha | string | ✔ | Chaine de caractères hexadécimale (40 chiffres) représentant la synthèse SHA1 du fichier. |
| platforms_to_sync | string | ✔ | Liste des plateformes pour lesquelles ce fichier est valide. Valeurs possibles : toutes, Windows, macOS, Linux, Android, iPhoneOS, Switch. Non sensible à la casse. |
| upload_batch_id | uint64 | ✔ | Le batch_id renvoyé par BeginAppUploadBatch ci-dessus. |
Appelez cette API pour initier le chargement d'un nouveau fichier (ou une nouvelle version d'un fichier existant) vers Steam Cloud pour le compte en question. Les nouvelles versions de fichiers existants remplaceront ces derniers.
Veuillez noter que pour les paramètres de liste, comme « platforms_to_sync », lorsqu'utilisés comme paramètres GET, la syntaxe se présente comme suit.
&platforms_to_sync[0]=macos&platforms_to_sync[1]=windows
Dans un champ codé en JSON contenu dans un paramètre POST, elle se présente ainsi :
"platforms_to_sync": ["macos", "windows"]
Données de la réponse :
| Nom | Type | Description |
|---|
| ugcid | uint64 | ID unique de fichier (accessoire). |
| timestamp | uint32 | Horodatage de ce changement au format horaire Unix. |
| url_host | string | Adresse complète (FQDN) de l'hôte à laquelle charger le fichier. |
| url_path | string | Chemin de la requête. Veuillez noter qu'une barre oblique (/) est déjà incluse. |
| use_https | bool | Réglez ce paramètre sur true si vous devez utiliser HTTPS pour effectuer le chargement (true d'une manière générale). |
| request_headers | Voir ci-dessous. | Liste d'entêtes HTTP que vous devez régler sur la requête PUT suivante. |
La liste « request_headers » contient ces données :
| Nom | Type | Description |
|---|
| name | string | Nom de l'entête. |
| Valeur | string | Valeur de l'entête. |
Pour charger le fichier, effectuez une requête PUT vers
https://<url_host><url_path> dans laquelle tous les entêtes HTTP spécifiés ci-dessus ont la valeur stipulée. En cas de succès, vous recevrez peut-être une réponse « 200 OK », « 201 Created » ou « 204 No Content », en fonction du service de stockage.
Cette requête peut ressembler à cela :
PUT https://steamcloud-us-west1.storage.googleapis.com/00/00/00/00/1234/012_3_4A77D494_9D267_1464.dat?GoogleAccessId=numbersandletters@developer.gserviceaccount.com&Expires=1595961837&Signature=morestuffhere HTTP/1.1
Host: steamcloud-us-west1.storage.googleapis.com
Content-Type: application/octet-stream
Content-Length: <body length>
Header-from-Steam1: value1
Header-from-Steam2: value2
<file data>
Une fois cela terminé (qu'il s'agisse d'un succès ou non), appelez :
CommitHTTPUpload
Exemple
POST https://api.steampowered.com/ICloudService/CommitHTTPUpload/v1/ HTTP/1.1
Host: api.steampowered.com
Content-Type: application/x-www-form-urlencoded
Content-Length: <body length>
access_token=<token>&input_json={ "appid": "1234", "transfer_succeeded": "1", "filename": "%25WinAppDataLocal%25Foobar%2FGamename%2Fcloud%2Fgames%2Fsave.sav", "file_sha": "FDFE308499263F9361B472648E9F49DC0B8799C8" }
| Nom | Type | Requis | Description |
|---|
| access_token | string | ✔ | Jeton d'accès OAuth du compte. |
| appid | uint32 | ✔ | Votre AppID. |
| transfer_succeeded | bool | ✔ | true si la requête PUT a réussi. |
| filename | string | ✔ | Nom du fichier. |
| file_sha | string | ✔ | Chaine de caractères hexadécimale (40 chiffres) représentant la synthèse SHA1 du fichier. |
La réponse à cette API ne possède actuellement qu'un seul champ, « file_committed ». Elle renverra true si Steam a pu appliquer le changement avec succès. Si elle renvoie false, alors le chargement a échoué, le nouveau fichier n'a pas été enregistré ou, s'il s'agissait d'une mise à jour sur un fichier existant, ce dernier existe toujours et sera renvoyé dans toute requête d'énumération ou de téléchargement future.
Delete
Exemple
POST https://api.steampowered.com/ICloudService/Delete/v1/ HTTP/1.1
Host: api.steampowered.com
Content-Type: application/x-www-form-urlencoded
Content-Length: <body length>
access_token=<token>&input_json={ "appid": "1234", "filename": "%25WinAppDataLocal%25Foobar%2FGamename%2Fcloud%2Fgames%2Fsave.sav" }
| Nom | Type | Requis | Description |
|---|
| access_token | string | ✔ | Jeton d'accès OAuth du compte. |
| appid | uint32 | ✔ | Votre AppID. |
| filename | string | ✔ | Nom du fichier à supprimer. |
Cette API supprimera le fichier spécifié sur Steam Cloud pour le compte concerné. La suppression de fichiers est irréversible, aucune version précédente ne sera conservée. Il n'y a aucune donnée dans le corps de réponse de cette API.
