Steamworks 文献库
ICloudService 接口
提供 Steam 用户的 Steam 云文件的访问权。 这主要是为了为您的游戏启用跨平台保存。 游戏的 Steam 版本可以使用 Steamworks 云功能(ISteamRemoteStorage API 或 Steam Auto-Cloud)。 非 Steam 版本可以使用此 WebAPI 访问文件并上传新版本。

您的游戏将需要获得用户的许可才能访问其 Steam 云文件。 可以通过 OAuth 完成。 请注意,您最好应该同时请求 read_cloudwrite_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_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上次修改文件的时间(Unix 时间戳格式)
file_sizeuint32文件大小的字节数
urlstring可以用来下载文件的 URL
steamid_creatoruint64用户的 SteamID。
flagsuint32仅供 Steam 内部使用
platforms_to_syncstring此文件对其有效的平台列表。 请参阅上传文件以获取可能值的列表。
file_shastring十六进制字符串(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_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 表明此批次中的所有操作都已尝试完毕,并会立即允许所有刚刚请求的批次。

示例:
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_tokenstring用户的 OAuth 访问令牌
appiduint32您的 App ID
batch_iduint64此批次的 ID 号
batch_eresultuint32此批次的结果(见下方解释)

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_tokenstring用户的 OAuth 访问令牌
appiduint32您的 App ID
transfer_succeededbool如果 PUT 请求成功,为 true
filenamestring文件名
file_shastring十六进制字符串(40 位数字),代表文件的 SHA1 摘要。
platforms_to_syncstring此文件对其有效的平台列表。 可能的值:All、Windows、MacOS、Linux、Android、iPhoneOS、Switch。 不区分大小写。
upload_batch_iduint64以上 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"]

响应数据:
名称类型描述
ugciduint64唯一文件 id(非必需)
timestampuint32此变更的 Unix 格式时间戳
url_hoststring会将文件上传到的主机的 FQDN
url_pathstring要请求的路径。 请注意,当前已经包括一个前导斜杠字符(/)。
use_httpsbool如果必须使用 HTTPS 执行上传,则设置为 true(通常始终为 true)
request_headers见下方您必须在后续 PUT 请求上设置的 HTTP 标头列表

“request_headers”列表包含以下数据:
名称类型描述
namestring标头名称
valuestring标头值

要上传文件,请向 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_tokenstring用户的 OAuth 访问令牌
appiduint32您的 App ID
transfer_succeededbool如果 PUT 请求成功,为 true
filenamestring文件名
file_shastring十六进制字符串(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_tokenstring用户的 OAuth 访问令牌
appiduint32您的 App ID
filenamestring要删除的文件的名称

该 API 将从用户的 Steam 云中删除指定的文件。 删除文件是永久的;并不会保留该文件的先前版本。 此 API 的响应中没有主体数据。