> ## 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.

# 顯示人員系統中的人員

> 結合 People、Presence、Profile 和 Leaderboards 服務與 People 代稱，以顯示 XBOX Live 人員清單資料的呼叫模式。

<a id="top" />

本主題說明使用人員系統顯示人員的程式碼流程。以下是一些範例呼叫流程案例，示範遊戲如何從與 People 相關的服務取得資料。

* [目前在遊戲中的使用者清單](#loucig)
* [目前使用者的人員中在線上者的清單](#lotcupwao)
* [包含隨機使用者的全域排行榜](#glcru)
* [使用者人員的排行榜](#loup)

XBOX Live 中的服務只會傳回該服務所擁有的資料，且只會傳回使用者的 XUID 參考。
以下是一些範例。

* *People 服務*只擁有並傳回使用者人員清單上的 XUID，以及每個 XUID 的一些非常基本的資訊 (例如最愛狀態)。
* *Presence 服務*擁有 XUID 線上狀態資訊的相關資料。
* *Leaderboards 服務*擁有 XUID 清單的排名資訊。

若要在體驗中呈現人員清單，您必須呼叫多個服務。這是因為顯示名稱和玩家代號資訊只會從 *Profile 服務*傳回，絕不會從任何其他服務傳回。

服務 API 的一般呼叫模式是先進行一次來回行程，從最能篩選或排序清單的服務取得 XUID 清單，然後視需要同時對其他服務進行來回呼叫，以取得每個 XUID 所需的任何其他中繼資料。
對於影像，可能需要第三次來回呼叫，才能從影像 URL 取得影像。

為了減少取得使用者人員清單相關資料所需的來回行程次數，相關服務已引進 People *代稱*。
此功能可讓呼叫端抽象地向主要服務表示，它應該從 People 服務取得使用者的人員清單，然後使用該組 XUID 來限定傳回的範圍。

[返回本主題頂端。](#top)

<a id="loucig" />

## 目前在遊戲中的使用者清單

**遊戲擁有：**

遊戲中其他使用者的隨機 XUID 清單。

**目標：**

為每位其他使用者呈現最少的資訊。

**要呈現的欄位 \[擁有服務]：**

`GameDisplayName` \[Profile]

**呼叫流程：**

以 XUID 清單呼叫 `Profile`。

[返回本主題頂端。](#top)

<a id="lotcupwao" />

## 目前使用者的人員中在線上者的清單

**遊戲擁有：**

目前使用者的 XUID。

**目標：**

呈現目前使用者人員清單中線上使用者的豐富清單。

**要呈現的欄位 \[擁有服務]：**

* 最愛指標 \[People]
* 顯示圖片 \[Profile]
* `GameDisplayName` \[Profile]
* 基本線上狀態 (綠色圓圈) \[Presence]

**呼叫流程：**

1. 呼叫 `Presence`，傳入 `People` 代稱，以取得使用者每位人員的 XUID 和線上狀態。
2. 平行進行：
   1. 呼叫 `Profile`，傳入整個 XUID 清單，以取得每個 XUID 的顯示名稱和圖片 URL。然後，取得每個圖片 URL 的影像。
   2. 呼叫 `People`，傳入 XUID 清單，以找出其中是否有使用者的最愛。

[返回本主題頂端。](#top)

<a id="glcru" />

## 包含隨機使用者的全域排行榜

**遊戲擁有：**

排行榜的識別碼/名稱。

**目標：**

為排行榜上的每位使用者呈現基本資訊。

**要呈現的欄位 \[擁有服務]：**

* 最愛指標 \[People]
* `GameDisplayName` \[Profile]
* 排名 \[Leaderboards]
* 分數 \[Leaderboards]

**呼叫流程：**

1. 呼叫 `Leaderboards`，以取得特定排行榜的 XUID、排名和分數。
2. 平行進行：
   * 呼叫 `Profile`，傳入 XUID 清單，以取得每個 XUID 的顯示名稱和圖片 URL。
   * 呼叫 `People`，傳入 XUID 清單，以找出其中是否有使用者的最愛。

[返回本主題頂端。](#top)

<a id="loup" />

## 使用者人員的排行榜

**遊戲擁有：**

* 排行榜的識別碼/名稱
* 目前使用者的 XUID

**目標：**

為排行榜上的每位使用者呈現基本資訊。

**要呈現的欄位 \[擁有服務]：**

* 最愛指標 \[People]
* `GameDisplayName` \[Profile]
* 排名 \[Leaderboards]
* 分數 \[Leaderboards]

**呼叫流程：**

1. 呼叫 `Leaderboards`，傳入 `People` 代稱，以取得限定於使用者人員清單之特定排行榜的 XUID、排名和分數。
2. 平行進行：
   * 呼叫 `Profile`，傳入 XUID 清單，以取得每個 XUID 的顯示名稱和圖片 URL。
   * 呼叫 `People`，傳入 XUID 清單，以找出其中是否有使用者的最愛。

[返回本主題頂端。](#top)


## Related topics

- [人員系統 (好友清單) 概念](/zh-TW/services/xbox-services/community/people-system/concepts/live-people-system-concepts-nav.md)
- [概念](/zh-TW/services/xbox-services/community/people-system/concepts/index.md)
- [人員系統 (好友清單) 概觀](/zh-TW/services/xbox-services/community/people-system/live-people-system-overview.md)
- [人員系統](/zh-TW/services/xbox-services/community/people-system/index.md)
- [人員系統 (好友清單)](/zh-TW/services/xbox-services/community/people-system/live-people-system-nav.md)