Steamworks ドキュメンテーション
ICloudServiceインターフェイス
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_tokenstringユーザーのOAuthアクセストークン
appiduint32ゲームのApp ID
extended_detailsboolファイルのダウンロードリンクなど、詳細が入ります。
countuint32列挙するファイルの最大数(デフォルトは500)
start_indexuint32列挙するファイルインデックスの開始(デフォルトは0)

ユーザーの、該当するゲーム用のSteamクラウドファイルを列挙します。 "start_index" がゼロで始まり、ユーザーが"count" を超えるファイルを持つ場合には必要に応じて反復処理します。

応答には二つのフィールドがあります:
名前説明
files以下参照ファイル詳細のリスト
total_filesuint32該当アプリのユーザーのSteamクラウドファイル内にあるファイルの合計数

ファイルリストは次のデータを含みます:
名前説明
appiduint32ゲームのApp ID
ugciduint64一意のファイルID
filenamestringファイル名
timestampuint64ファイルが最後に変更されたエポック時間
file_sizeuint32ファイルのサイズ(バイト単位)
urlstringファイルのダウンロードに使用されるURL
steamid_creatoruint64ユーザーのSteam ID
flagsuint32Steam内部使用のみ
platforms_to_syncstringこのファイルが有効なプラットフォームのリスト。 可能な値は「ファイルのアップロード」セクションを参照してください。
file_shastringファイルの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_tokenstringユーザーのOAuthアクセストークン
appiduint32ゲームのApp ID
machine_namestringソースマシンの名前、ユーザーがデバイスに適用したものが好ましい
files_to_uploadstring listこのバッチの一部としてアップロードされるすべてのファイルのリスト(新ファイル又は既存のファイルへのアップデート)
files_to_deletestring 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_iduint64 このバッチのID、CompleteAppUploadBatch呼び出しで使います
app_change_numberuint64この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説明説明
namestringヘッダー名ユーザーのOAuthアクセストークン
appiduint32ゲームのApp ID
batch_iduint64このバッチのID番号
batch_eresultuint32このバッチの結果(備考欄参照)

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_tokenstringユーザーのOAuthアクセストークン
appiduint32ゲームのApp ID
transfer_succeededboolファイルのサイズ(バイト単位)
filenamestringファイル名
file_shastringファイルのSHA1ダイジェストを表す16進文字列(40桁)。
platforms_to_syncstringこのファイルが有効なプラットフォームのリスト。 可能な値:All, Windows, MacOS, linux, Android, iPhoneOS, Switch. 大文字小文字の区別はありません。
upload_batch_iduint64上述の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"]

応答データ:
名前説明
ugciduint64一意のファイルID(必須ではありません)
timestampuint32この変更のエポックタイムスタンプ
url_hoststringファイルのアップロード先のホストFQDN
url_pathstringリクエストのパス 既に先頭にスラッシュ (/)が含まれていることに注意してください。
use_httpsboolアップロードの実行にHTTPSを使用する必要がある場合には(たいていの場合そうですが)、trueを設定してください。
request_headers以下参照後続のPUTリクエストで設定する必要があるHTTPヘッダーのリスト

"request_headers" リストは次のデータを含みます:
名前説明
namestringヘッダー名
valuestringヘッダーの値

ファイルをアップロードするには、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_tokenstringユーザーのOAuthアクセストークン
appiduint32ゲームのApp ID
transfer_succeededboolPUTリクエスト成功時はtrue
filenamestringファイル名
file_shastringファイルの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_tokenstringユーザーのOAuthアクセストークン
appiduint32ゲームのApp ID
filenamestring削除するファイルのファイル名

このAPIは指定のファイルをユーザーのSteamクラウドから削除します。 削除のファイルは永続的です。以前のバージョンのファイルは保持されません。 このAPIからの応答にボディデータはありません。