透過 REST 更新使用者的線上狀態

本主題提供更新 Rich Presence 字串的範例程式碼。若要在您的遊戲中更新 Rich Presence 字串，請在 JSON 物件中以適當的參數呼叫 Write Title URI。此 RESTful 呼叫也由 XBOX 服務 API (XSAPI) 包裝。如需與此呼叫相關之 API 的資訊，請參閱 XblPresenceSetPresenceAsync。 URI 如下所示：

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，呼叫如下所示：

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

它具有下列 JSON 本文。

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

使用包裝函式 API 時，這是對 XblPresenceSetPresenceAsync 的呼叫。如果您讓 XBOX 玩家資料保持最新狀態，就不需要在每次資料變更時重設 Rich Presence 字串以填入空白。在上一個範例中，使用的是目前地圖。當使用者嘗試讀取字串時，Presence 會在 XBOX 玩家資料中查閱資料以填入目前的值。即使使用者從一張地圖切換到另一張地圖，只要您將適當的事件傳送至 XBOX 玩家資料，就不需要在遊戲中重設 Rich Presence 字串。資料可能需要幾秒鐘的時間才能在 XBOX 玩家資料系統中移轉。當有人嘗試讀取使用者 12345 的 Rich Presence 時，服務會查看所要求的地區設定，並在傳回字串之前適當地將其格式化。在此案例中，假設使用者想要讀取 en-US 字串。讀取 Rich Presence 的運作方式如下。

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

如需此呼叫的詳細資訊，請參閱 GET (/users/xuid({xuid}))。此呼叫的包裝函式 API 是 XblPresenceGetPresenceAsync 或 XblPresenceGetPresenceForMultipleUsersAsync。在上一個範例中，您已要求 xuid 為 12345 之使用者的 PresenceRecord。您也要求詳細資料層級為 all。如果您未指定 all，就不會傳回 Rich Presence。相反地，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"
                    }
                  }
                ]
              }
            ]
          }

XBOX Services

PlayFab

TitleRequest 物件

ActivityRequest 物件

RichPresenceRequest 物件

​TitleRequest 物件

​ActivityRequest 物件

​RichPresenceRequest 物件

TitleRequest 物件

ActivityRequest 物件

RichPresenceRequest 物件