> ## 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 更新使用者的線上狀態

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

本主題提供更新 Rich Presence 字串的範例程式碼。

若要在您的遊戲中更新 Rich Presence 字串，請在 JSON 物件中以適當的參數呼叫 `Write Title` URI。

此 RESTful 呼叫也由 XBOX 服務 API (XSAPI) 包裝。
如需與此呼叫相關之 API 的資訊，請參閱 [XblPresenceSetPresenceAsync](/zh-TW/reference/live/xsapi-c/presence_c/functions/xblpresencesetpresenceasync)。

URI 如下所示：

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

下列欄位僅用於設定 Rich 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](/zh-TW/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](/zh-TW/reference/live/xsapi-c/presence_c/functions/xblpresencegetpresenceasync) 或 [XblPresenceGetPresenceForMultipleUsersAsync](/zh-TW/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-TW/services/xbox-services/community/presence/how-to/live-presence-howto-nav.md)
- [操作說明](/zh-TW/services/xbox-services/community/presence/how-to/index.md)
- [透過 XSAPI C 更新使用者的線上狀態](/zh-TW/services/xbox-services/community/presence/how-to/live-updating-user-presence.md)
- [取得使用者的線上狀態](/zh-TW/services/xbox-services/community/presence/how-to/live-getting-a-users-presence.md)
- [XblPresenceStopTrackingUsers](/zh-TW/reference/live/xsapi-c/presence_c/functions/xblpresencestoptrackingusers.md)