SteamユーザーのSteamクラウドファイルへのアクセスを提供します。 ほとんどの場合、クロスプラットフォームでのゲームのセーブデータを利用可能とするために使用されます。 ゲームのSteam版は、ISteamRemoteStorage APIまたはSteam Auto-Cloudを通じ、Steamworksクラウド機能を使用できます。 Steam版以外は、このWebAPIを使うことで、ファイルにアクセスして新バージョンをアップロードできます。
ゲームにおいて、ユーザーからSteamクラウドファイルにアクセスすることへの許可を得ている必要があります。 これは
OAuthで行えます。
read_cloud
許可と
write_cloud
許可の両方を要求することがほとんどです。
一般的なSteam
WebAPI概要、特に「サービスインターフェイス」の部分を参照してください。 GETリクエストはパラメーターをURL内に含めることができますが、POSTリクエストはすべてのパラメーターをリクエストボディに含めることを推奨します。
access-token
パラメーターは直接フォームエンコードされ、残りのパラメーターはその後
input-json
フィールドを介して設定された経由でJSON構造である必要があります。
整形式で認証されたリクエストへの応答は通常
200 OK
です。 リクエストが失敗した場合、
x-eresult
ヘッダー内に詳細なSteamエラーコードが入ります。 "success"の値は1です。 それ以外の値は全てエラーです。詳細は、
steam_api.h を参照してください。
ファイルの列挙
read_cloud
OAuthアクセスが必要です。
EnumerateUserFiles
例:
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
名前 | 型 | 必須 | 説明 |
access_token | string | ✔ | ユーザーのOAuthアクセストークン |
appid | uint32 | ✔ | ゲームのApp ID |
extended_details | bool | | ファイルのダウンロードリンクなど、詳細が入ります。 |
count | uint32 | | 列挙するファイルの最大数(デフォルトは500) |
start_index | uint32 | | 列挙するファイルインデックスの開始(デフォルトは0) |
ユーザーの、該当するゲーム用のSteamクラウドファイルを列挙します。 "start_index" がゼロで始まり、ユーザーが"count" を超えるファイルを持つ場合には必要に応じて反復処理します。
応答には二つのフィールドがあります:
名前 | 型 | 説明 |
files | 以下参照 | ファイル詳細のリスト |
total_files | uint32 | 該当アプリのユーザーのSteamクラウドファイル内にあるファイルの合計数 |
ファイルリストは次のデータを含みます:
名前 | 型 | 説明 |
appid | uint32 | ゲームのApp ID |
ugcid | uint64 | 一意のファイルID |
filename | string | ファイル名 |
timestamp | uint64 | ファイルが最後に変更されたエポック時間 |
file_size | uint32 | ファイルのサイズ(バイト単位) |
url | string | ファイルのダウンロードに使用されるURL |
steamid_creator | uint64 | ユーザーのSteam ID |
flags | uint32 | Steam内部使用のみ |
platforms_to_sync | string | このファイルが有効なプラットフォームのリスト。 可能な値は「ファイルのアップロード」セクションを参照してください。 |
file_sha | string | ファイルのSHA1ダイジェストを表す16進文字列(40桁)。 |
ファイルのダウンロード
ファイルをダウンロードするには、上記のEnumerateUserFilesによって返されたURLに対し、GETリクエストを作成してください。
ファイルのアップロード
write_cloud
OAuthアクセスが必要です。
新ファイルのアップロード、既存ファイルの新バージョンのアップロード、Steamクラウドからファイルの削除等が、ファイルの変更に該当します。
一連のファイル変更アクションは一つの
バッチにラップされるべきです。 バッチは一連の変更の意図をSteamクラウドへ伝達するために使用され、ファイル間の競合の可能性を減らすのに役立ちます。
完全なバッチシーケンスは次のようになります:
-
BeginAppUploadBatch
呼び出しで、意図するアップロードや削除をリストします
- 0以上のuploadsの場合このシーケンスを使用:
-
BeginHTTPUpload
- HTTP
PUT
オペレーションでファイルをアップロード
-
CommitHTTPUpload
- 0以上のdeletesには、
Delete
を使用
-
CompleteAppUploadBatch
全てのアップロードおよびまたは削除が完全に成功してもしなくても必ず、
CompleteAppUploadBatch
を呼び出す必要があります。
CompleteAppUploadBatch
呼び出しをしないと、当該ユーザーのための新アップロード試行が数分実行されない状態が発生し、アプリは"too many pending requests(保留中のリクエストが多すぎます)"応答によってブロックされます。
BeginHTTPUpload
一連のファイル変更の最初の操作は
BeginAppUploadBatch
の呼び出しです。 この呼び出しによって、Steamクラウドへ意図する一連のアップロードと削除、アップデートを実行するユーザーのマシーンの情報を伝えます。
例:
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"] }
名前 | 型 | 必須 | 説明 |
access_token | string | ✔ | ユーザーのOAuthアクセストークン |
appid | uint32 | ✔ | ゲームのApp ID |
machine_name | string | ✔ | ソースマシンの名前、ユーザーがデバイスに適用したものが好ましい |
files_to_upload | string list | ✔ | このバッチの一部としてアップロードされるすべてのファイルのリスト(新ファイル又は既存のファイルへのアップデート) |
files_to_delete | string list | ✔ | このバッチの一部としてSteamクラウドから削除されるすべてのファイルのリスト |
このAPIを呼び出して、バッチのアップロードの開始します。
"files_to_upload"のようなリストパラメーターの場合、GETパラメーターとして使用する場合の構文は次の通りです:
&files_to_upload[0]=file1.sav&files_to_upload[1]=file2.sav
POSTパラメーターのJSONエンコードされたフィールドでは、次のようになります:
"files_to_upload": ["file1.sav", "file2.sav"]
応答データ:
名前 | 型 | 説明 |
batch_id | uint64 | このバッチのID、CompleteAppUploadBatch 呼び出しで使います |
app_change_number | uint64 | このAPIでは現在使われていません |
アプリケーションはこの応答から
batch_id
を記憶し、すべてのアップロードと削除が試行されてから、
CompleteAppUploadBatch
リクエストに提出します。
CompleteAppUploadBatch
すべてのアップロードと削除が試行されてから、成功したかに関わらず
CompleteAppUploadBatch
を呼び出す必要があります。 これにより、このバッチに対するすべての操作が試行されたことをSteamに示し、Steamは新規にリクエストされたバッチを許可するようになります。
例:
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" }
名前 | Type | 説明 | 説明 |
name | string | ヘッダー名 | ユーザーのOAuthアクセストークン |
appid | uint32 | ✔ | ゲームのApp ID |
batch_id | uint64 | ✔ | このバッチのID番号 |
batch_eresult | uint32 | ✔ | このバッチの結果(備考欄参照) |
batch_eresult
パラメーターは1 (成功)または2(失敗)です。 技術的にはこれは
EResult
値です (リストは
steam_api.hを参照してください。) このメソッドでは、Steamに成功または失敗を示すだけで十分です。
このAPIからの応答にボディデータはありません。
BeginHTTPUpload
2パートのAPIでアップロードを完了します。 最初にBeginHTTPUploadを呼び出してファイルをアップロードする場所の詳細を取得し、それが完了したらCommitHTTPUploadを呼び出します。
例:
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", }
名前 | 型 | 必須 | 説明 |
access_token | string | ✔ | ユーザーのOAuthアクセストークン |
appid | uint32 | ✔ | ゲームのApp ID |
transfer_succeeded | bool | ✔ | ファイルのサイズ(バイト単位) |
filename | string | ✔ | ファイル名 |
file_sha | string | ✔ | ファイルのSHA1ダイジェストを表す16進文字列(40桁)。 |
platforms_to_sync | string | ✔ | このファイルが有効なプラットフォームのリスト。 可能な値:All, Windows, MacOS, linux, Android, iPhoneOS, Switch. 大文字小文字の区別はありません。 |
upload_batch_id | uint64 | ✔ | 上述のBeginAppUploadBatch によって返されるbatch_id |
ユーザーがSteamクラウドに新しいファイル(または既存のファイルの新バージョン)のアップロードを開始する時にこのAPIを呼び出します。 既存ファイルの新バージョンが、既存のバージョンを上書きします。
"platforms_to_sync"のようなリストパラメーターの場合、GETパラメーターとして使用する場合の構文は次の通りです:
&platforms_to_sync[0]=macos&platforms_to_sync[1]=windows
POSTパラメーターのJSONエンコードされたフィールドでは、次のようになります:
"platforms_to_sync": ["macos", "windows"]
応答データ:
名前 | 型 | 説明 |
ugcid | uint64 | 一意のファイルID(必須ではありません) |
timestamp | uint32 | この変更のエポックタイムスタンプ |
url_host | string | ファイルのアップロード先のホストFQDN |
url_path | string | リクエストのパス 既に先頭にスラッシュ (/ )が含まれていることに注意してください。 |
use_https | bool | アップロードの実行にHTTPSを使用する必要がある場合には(たいていの場合そうですが)、trueを設定してください。 |
request_headers | 以下参照 | 後続のPUTリクエストで設定する必要があるHTTPヘッダーのリスト |
"request_headers" リストは次のデータを含みます:
名前 | 型 | 説明 |
name | string | ヘッダー名 |
value | string | ヘッダーの値 |
ファイルをアップロードするには、
https://<url_host><url_path>にPUTリクエストをを送信します。ここでは、上記で指定されたHTTPヘッダーは指定の値を持ちます。 成功時に200 OK、プロバイダーによっては201 Created、204 No Content responseの応答が返されます。
このリクエストはこのように見えます:
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>
成功、失敗のいずれの場合も完了時には次を呼び出します:
CommitHTTPUpload
例:
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" }
名前 | 型 | 必須 | 説明 |
access_token | string | ✔ | ユーザーのOAuthアクセストークン |
appid | uint32 | ✔ | ゲームのApp ID |
transfer_succeeded | bool | ✔ | PUTリクエスト成功時はtrue |
filename | string | ✔ | ファイル名 |
file_sha | string | ✔ | ファイルのSHA1ダイジェストを表す16進文字列(40桁)。 |
このAPIへの応答は現時点で単一のフィールド "file_committed"を持ち、Steamが変更を完全に実行した場合にはtrueとなります。 アップロードが失敗した場合は、falseです。新しいファイルは記録されず、既存のファイルへのアップデートがある場合、既存ファイルは存在したままで、将来の列挙/ダウンロードリクエストによって返されます。
Delete
例:
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" }
名前 | 型 | 必須 | 説明 |
access_token | string | ✔ | ユーザーのOAuthアクセストークン |
appid | uint32 | ✔ | ゲームのApp ID |
filename | string | ✔ | 削除するファイルのファイル名 |
このAPIは指定のファイルをユーザーのSteamクラウドから削除します。 削除のファイルは永続的です。以前のバージョンのファイルは保持されません。 このAPIからの応答にボディデータはありません。