提供 Steam 用户的 Steam 云文件的访问权。 这主要是为了为您的游戏启用跨平台保存。 游戏的 Steam 版本可以使用 Steamworks 云功能(ISteamRemoteStorage API 或 Steam Auto-Cloud)。 非 Steam 版本可以使用此 WebAPI 访问文件并上传新版本。
您的游戏将需要获得用户的许可才能访问其 Steam 云文件。 可以通过
OAuth 完成。 请注意,您最好应该同时请求
read_cloud
和
write_cloud
权限。
另请参阅一般的 Steam
WebAPI 概述文档,具体而言是标题为“服务接口”的章节。 可以使用 URL 中的参数来完成 GET 请求,但是对于 POST 请求,建议将所有参数都放在请求正文中。
access-token
参数是直接经过形式编码(form-encoded)的,然后其余参数应位于通过
input-json
字段设置的 JSON 结构中。
对格式正确且经过身份验证的请求的响应通常为
200 OK
。 但是,请求也可能失败——详细的 Steam 错误代码可以在
x-eresult
标头中找到。 “成功”的值为 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 | 上次修改文件的时间(Unix 时间戳格式) |
file_size | uint32 | 文件大小的字节数 |
url | string | 可以用来下载文件的 URL |
steamid_creator | uint64 | 用户的 SteamID。 |
flags | uint32 | 仅供 Steam 内部使用 |
platforms_to_sync | string | 此文件对其有效的平台列表。 请参阅上传文件以获取可能值的列表。 |
file_sha | string | 十六进制字符串(40 位数字),代表文件的 SHA1 摘要。 |
下载文件
要下载文件,只需对上述 EnumerateUserFiles 返回的 URL 进行 GET 请求即可。
修改文件
需要
write_cloud
OAuth 权限。
会对文件进行修改,包括上传新文件、上传已有文件的新版本及从 Steam 云删除文件。
应将一组文件修改操作包装至一个
Batch(批次) 中。 Batch 用来告诉 Steam 云您的修改集意图为何,并帮助减少文件冲突的可能性。
完整的批次序列看起来如下:
-
BeginAppUploadBatch
调用,列出要进行的更新和删除
- 0 或更多 upload,使用以下序列:
-
BeginHTTPUpload
- HTTP
PUT
上传文件的操作
-
CommitHTTPUpload
- 0 或更多 delete,使用
Delete
-
CompleteAppUploadBatch
请注意,不论所有上传和/或删除是否成功完成,您都必须调用
CompleteAppUploadBatch
。 如果未调用
CompleteAppUploadBatch
,将会导致在几分钟的时间内为该用户进行新的上传尝试,而应用也会被“待处理请求过多”这一响应阻挡。
BeginAppUploadBatch
为文件修改集进行的第一个操作是调用
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 表明此批次中的所有操作都已尝试完毕,并会立即允许所有刚刚请求的批次。
示例:
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" }
名称 | 类型 | 描述 | 描述 |
access_token | string | ✔ | 用户的 OAuth 访问令牌 |
appid | uint32 | ✔ | 您的 App ID |
batch_id | uint64 | ✔ | 此批次的 ID 号 |
batch_eresult | uint32 | ✔ | 此批次的结果(见下方解释) |
batch_eresult
参数应为 1(成功)或 2(失败)。 从技术上来说,这是一个
EResult
值(请参
steam_api.h 以获取完整列表)。 此方法只需向 Steam 说明是成功或失败便足矣。
此 API 的响应中没有主体数据。
BeginHTTPUpload
上传是通过一个两部分的 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"] }
名称 | 类型 | 是否必需 | 描述 |
access_token | string | ✔ | 用户的 OAuth 访问令牌 |
appid | uint32 | ✔ | 您的 App ID |
transfer_succeeded | bool | ✔ | 如果 PUT 请求成功,为 true |
filename | string | ✔ | 文件名 |
file_sha | string | ✔ | 十六进制字符串(40 位数字),代表文件的 SHA1 摘要。 |
platforms_to_sync | string | ✔ | 此文件对其有效的平台列表。 可能的值:All、Windows、MacOS、Linux、Android、iPhoneOS、Switch。 不区分大小写。 |
upload_batch_id | uint64 | ✔ | 以上 BeginAppUploadBatch 返回的 batch_id |
调用此 API 来为用户开始将新文件(或现有文件的新版本)上传到 Steam 云。 现有文件的新版本将覆盖现有版本。
请注意,对于列表参数(如“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 | 此变更的 Unix 格式时间戳 |
url_host | string | 会将文件上传到的主机的 FQDN |
url_path | string | 要请求的路径。 请注意,当前已经包括一个前导斜杠字符(/ )。 |
use_https | bool | 如果必须使用 HTTPS 执行上传,则设置为 true(通常始终为 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 响应,具体取决于存储空间提供商。
该请求可能看起来如下:
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 | ✔ | 十六进制字符串(40 位数字),代表文件的 SHA1 摘要。 |
当前对此 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 的响应中没有主体数据。