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 类型。 如果响应失败,则会收到 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日