> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 通过 REST 更新用户的 Presence

> 使用 Write Title URI 更新 XBOX Live Rich Presence 的 REST 参考，包括 TitleRequest、ActivityRequest 和 RichPresenceRequest 字段。

本主题提供更新 Rich Presence 字符串的示例代码。

要在游戏中更新 Rich Presence 字符串，请调用 `Write Title` URI 并在 JSON 对象中传入适当的参数。

这个 RESTful 调用也由 XBOX Service API (XSAPI) 包装。
有关与此调用相关的 API 的信息，请参阅 [XblPresenceSetPresenceAsync](/reference/live/xsapi-c/presence_c/functions/xblpresencesetpresenceasync)。

URI 如下所示：

```uri theme={null}
POST /users/xuid({xuid})/devices/current/titles/current
```

以下字段仅用于设置 Rich Presence 字符串。
其他可选字段与写入游戏的 presence 相关，但本主题不列出。

## TitleRequest 对象

| 属性       | 类型              | 必需 | 描述                                    |
| -------- | --------------- | -- | ------------------------------------- |
| Activity | ActivityRequest | 否  | 描述游戏内信息的记录（Rich Presence 和媒体信息（如果可用）） |

## ActivityRequest 对象

| 属性           | 类型                  | 必需 | 描述                                   |
| ------------ | ------------------- | -- | ------------------------------------ |
| richPresence | RichPresenceRequest | 否  | 要使用的 Rich Presence 字符串的 friendlyName |

## RichPresenceRequest 对象

| 属性   | 类型     | 必需 | 描述                                   |
| ---- | ------ | -- | ------------------------------------ |
| Id   | String | 是  | 要使用的 Rich Presence 字符串的 friendlyName |
| Scid | String | 是  | 指示定义 Rich Presence 字符串位置的 scid       |

例如，要更新 xuid 为 12345 的用户的 Rich Presence，调用如下所示：

```uri theme={null}
POST /users/xuid(12345)/devices/current/titles/current
```

它具有以下 JSON 主体。

```json theme={null}
          {
            activity:
            {
              richPresence:
              {
                id:"playingMap",
                scid:"0000-0000-0000-0000-01010101"
              }
            }
          }
```

使用包装 API，这是对 [XblPresenceSetPresenceAsync](/reference/live/xsapi-c/presence_c/functions/xblpresencesetpresenceasync) 的调用。

如果你保持 XBOX 玩家数据处于最新状态，则不需要每次数据更改时都重置 Rich Presence 字符串以填入空白。
在前面的示例中，使用了当前地图。

当用户尝试读取字符串以填入当前值时，Presence 会在 XBOX 玩家数据中查找数据。
即使用户正在从一张地图切换到另一张地图，只要你向 XBOX 玩家数据发送适当的事件，就不必在游戏中重置 Rich Presence 字符串。

数据可能需要几秒钟才能通过 XBOX 玩家数据系统迁移。

当某人尝试读取用户 12345 的 Rich Presence 时，服务会查看请求的区域设置，并在返回字符串之前对其进行适当格式化。
在这种情况下，假设某个用户想要读取 en-US 字符串。

读取 Rich Presence 的方式如下。

```uri theme={null}
GET /users/xuid(12345)?level=all
```

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

它的包装 API 为 [XblPresenceGetPresenceAsync](/reference/live/xsapi-c/presence_c/functions/xblpresencegetpresenceasync) 或 [XblPresenceGetPresenceForMultipleUsersAsync](/reference/live/xsapi-c/presence_c/functions/xblpresencegetpresenceformultipleusersasync)。

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

如果未指定 `all`，则不会返回 Rich Presence。相反，`all` 在 JSON 响应中返回以下内容。

```json theme={null}
          {
            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"
                    }
                  }
                ]
              }
            ]
          }
```


## Related topics

- [Rich Presence 示例代码](/zh-CN/services/xbox-services/community/presence/how-to/live-presence-howto-nav.md)
- [操作指南](/zh-CN/services/xbox-services/community/presence/how-to/index.md)
- [通过 XSAPI C 更新用户的 Presence](/zh-CN/services/xbox-services/community/presence/how-to/live-updating-user-presence.md)
- [XBOX 成就管理器 API 概述](/zh-CN/services/xbox-services/player-data/achievements/achievements-manager/live-achievements-manager-overview.md)
- [XR-115 在游戏中添加和移除用户或控制器](/zh-CN/publishing/certification/xr/xr-115.md)