Skip to main content

REST API 概览

欢迎使用 PlayFab REST API 参考。你可以在此获取参考资料,并了解我们的 API 是如何运行的。每份 API 参考都分为若干不同的部分。

端点

端点是你可以对其发起 API 请求的 HTTP URL。它的前面会带有 REST 方法类型(例如 GET、POST)。此外,需要将 titleId 替换为你游戏的 titleId。 示例:

请求正文

请求正文是以 JSON 形式发送到我们 API 服务的对象模型。这些模型包含需要作为负载随 API 一起发送的属性。有些属性标记为必填,其他为可选

响应

API 服务要么返回 200 OK,同时附带一个可反序列化为模型的 JSON 负载。在下方示例中,Login API 调用会被反序列化为 LoginResult 类型。 带有 LoginResult 的 200 OK 响应示例 如果响应失败,则会收到 4XX 错误响应。400 Bad Request 通常是因为 API 调用中缺少参数,或存在其他原因,例如超出速率限制以及校验错误。如果遇到 4XX 错误,最好检查请求参数与认证令牌,确保它们正确无误。ApiErrorWrapper 对象包含关于错误的重要信息,包括来自服务端的错误代码、错误详情和错误消息,可帮助定位问题。

安全

每个 API 都有某种形式的安全机制,需要在每个请求的头部中传入。请参阅相应章节了解需要设置的内容。有时它是登录请求返回的会话票据;如果你在进行服务端 API 请求,它也可能是游戏的 secret key。

并发

API 服务的设计能够处理来自每款游戏的大量并发调用,但对于访问单个玩家或其他单一实体(例如角色或群组)的并发调用数量存在限制。如果超过并发限制,API 会返回 APIConcurrentRequestLimitExceededConcurrentEditError 错误代码。总体而言,同时针对同一玩家发起多个读请求通常是安全的,但最好每次只发一个更新请求。

模型定义

API 服务的每个响应可以包含一个或多个模型。这些模型位于 ApiErrorWrapper 下方,并且每个模型在与 API 相同的文档中呈现。每个模型也会在其响应父模型中被链接引用。你还可以访问每个 API 页面中的 Definitions 部分,查看该 API 支持的模型列表。

事件模型定义

PlayStream 事件模型参考包含自动生成的 PlayStream 事件类型的模型定义。每种事件类型都有一组属性,这些属性会在事件被发送到任何地方时随事件数据一并包含。
最后修改于 2026年8月31日