通过 REST 更新用户的状态

本主题提供用于更新丰富状态字符串的示例代码。

若要更新游戏中的丰富状态字符串，请使用 JSON 对象中的适当参数调用 Write Title URI。

此 RESTful 调用也由 Xbox 服务 API (XSAPI) 包装。 有关与此调用相关的 API 的信息，请参阅 XblPresenceSetPresenceAsync。

URI 如下所示：

POST /users/xuid({xuid})/devices/current/titles/current

以下字段仅用于设置丰富状态字符串。 其他可选字段与游戏的编写状态相关，但本主题中未列出这些字段。

TitleRequest 对象

ActivityRequest 对象

RichPresenceRequest 对象

例如，若要更新 xuid 为 12345 的用户的丰富状态，调用如下所示：

POST /users/xuid(12345)/devices/current/titles/current

它具有以下 JSON 正文。

          {
            activity:
            {
              richPresence:
              {
                id:"playingMap",
                scid:"0000-0000-0000-0000-01010101"
              }
            }
          }

使用包装器 API，这是对 XblPresenceSetPresenceAsync 的调用。

如果将 Xbox Player Data 保持最新，则每次在数据发生更改时，无需重置丰富状态字符串即可填充空白。 在前面的示例中，使用的是当前地图。

当用户试图读取字符串来填充当前值时，状态会在 Xbox Player Data 中查找数据。 即使用户正在从一个地图切换到另一个地图，只要你向 Xbox 玩家数据发送适当的事件，就不必重置游戏中的丰富状态字符串。

数据通过 Xbox Player Data 系统迁移可能需要几秒钟的时间。

当有人试图读取用户 12345 的丰富状态时，该服务会查看所请求的区域设置，并在返回字符串之前先适当地格式化字符串。 在这里，假设用户想要读取 en-US 字符串。

读取丰富状态的方式如下所示。

GET /users/xuid(12345)?level=all

有关此调用的详细信息，请参阅 GET (/users/xuid({xuid}))。

此项的包装器 API 为 XblPresenceGetPresenceAsync 或 XblPresenceGetPresenceForMultipleUsersAsync。

在前面的示例中，你已请求 xuid 为 12345 的用户的 PresenceRecord。 你还请求详细信息级别为 all。

如果未指定 all，则不会返回丰富状态。 相反，all 会在 JSON 响应中返回以下内容。

          {
            xuid:"12345",
            state:"online",
            devices:
            [
              {
                type:"D",
                titles:
                [
                  {
                    id:"12345",
                    name:"Buckets are Awesome",
                    lastModified:"2022-08-17T07:15:23.4930000",
                    placement: "full",
                    state:"active",
                    activity:
                    {
                      richPresence:"Playing on map:Mountains"
                    }
                  }
                ]
              }
            ]
          }