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

# 取得遊戲管理型排行榜

> 讀取遊戲管理型 XBOX Live 排行榜的 XSAPI 範例程式碼，包括完整結果、指定排名周圍的檢視，以及指定玩家周圍的查詢。

**內容**

* [取得整個排行榜](#gael)
* [取得指定排名周圍的排行榜](#galaasr)
* [取得指定玩家周圍的排行榜](#galaasp)

本主題說明如何取得遊戲管理型排行榜的值。

<a id="gael" />

## 取得整個排行榜

使用 [XblLeaderboardGetLeaderboardAsync](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync) 傳回指定排行榜的值。結果會從排行榜頂端開始，依排名遞減的順序傳回。查詢以遊戲管理型統計資料為基礎的排行榜時，請務必將 `queryType` 欄位設定為 `XblLeaderboardQueryType::TitleManagedStatBackedGlobal` 或 `XblLeaderboardQueryType::TitleManagedStatBackedSocial`。

**C API**

```cpp theme={null}
auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*
    size_t resultSize;
    HRESULT hr = XblLeaderboardGetLeaderboardResultSize(asyncBlock, &resultSize);

    if (SUCCEEDED(hr))
    {
        leaderboardBuffer.resize(resultSize);
        XblLeaderboardResult* leaderboard{};

        hr = XblLeaderboardGetLeaderboardResult(asyncBlock, resultSize, leaderboardBuffer.data(), &leaderboard, nullptr);

        if (SUCCEEDED(hr))
        {
            // Use XblLeaderboardResult in result
            for (auto row = 0u; row < leaderboard->rowsCount; ++row)
            {
                std::stringstream rowText;
                rowText << leaderboard->rows[row].xboxUserId << "\t";

                for (auto column = 0u; column < leaderboard->rows[row].columnValuesCount; ++column)
                {
                    rowText << leaderboard->rows[row].columnValues[column] << "\t";
                }
            }
        }
    }
};

// XblLeaderboardQuery is set up to query for all leaderboard items here
// see example code in sections below showing how to run other queries
XblLeaderboardQuery leaderboardQuery = {}; 
pal::strcpy(leaderboardQuery.scid, sizeof(leaderboardQuery.scid), scid.c_str()) 
leaderboardQuery.statName = statName.c_str(); 
leaderboardQuery.queryType = XblLeaderboardQueryType::TitleManagedStatBackedGlobal;


HRESULT hr = XblLeaderboardGetLeaderboardAsync(
    xboxLiveContext,
    leaderboardQuery,
    asyncBlock.get());
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* since the callback will take over ownership.
    // If the call fails, the std::unique_ptr will keep ownership and delete the XAsyncBlock*
    asyncBlock.release();
}
```

**參考**

* [XAsyncBlock](/zh-TW/reference/system/xasync/structs/xasyncblock)
* [XblLeaderboardGetLeaderboardAsync](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync)
* [XblLeaderboardGetLeaderboardResult](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardresult)
* [XblLeaderboardGetLeaderboardResultSize](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardresultsize)
* [XblLeaderboardQuery](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery)
* [XblLeaderboardResult](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardresult)
* [XblLeaderboardQueryType](/zh-TW/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardquerytype)

<a id="galaasr" />

## 取得指定排名周圍的排行榜

您可以在建立 [XblLeaderboardQuery](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery) 時指定查詢條件，以從排行榜查詢取得篩選後的結果。
若要取得指定排名周圍的排行榜值，請使用上方範例中的程式碼，但將建立 XblLeaderboardQuery 的程式碼行替換為下列程式碼：

**C API**

```cpp theme={null}
XblLeaderboardQuery leaderboardQuery = {};
pal::strcpy(leaderboardQuery.scid, sizeof(leaderboardQuery.scid), scid.c_str());
leaderboardQuery.statName = statName.c_str();
leaderboardQuery.skipResultToRank = 100;
leaderboardQuery.maxItems = 100;
leaderboardQuery.queryType = XblLeaderboardQueryType::TitleManagedStatBackedGlobal;
```

**參考**

* [XblLeaderboardQuery](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery)

<a id="galaasp" />

## 取得指定玩家周圍的排行榜

若要取得指定玩家周圍的排行榜值，請使用上方範例中的程式碼，但將建立 [XblLeaderboardQuery](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery) 的程式碼行替換為下列程式碼：

**C API**

```cpp theme={null}
XblLeaderboardQuery leaderboardQuery = {};
pal::strcpy(leaderboardQuery.scid, sizeof(leaderboardQuery.scid), scid.c_str());
leaderboardQuery.statName = statName.c_str();
leaderboardQuery.skipToXboxUserId = xboxUserId;
leaderboardQuery.maxItems = 100;
leaderboardQuery.queryType = XblLeaderboardQueryType::TitleManagedStatBackedGlobal;
```

**參考**

* [XblLeaderboardQuery](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardquery)


## Related topics

- [遊戲管理型統計資料與排行榜範例程式碼](/zh-TW/services/xbox-services/player-data/stats-leaderboards/title-managed/how-to/live-statslb-tm-howto-nav.md)
- [操作說明](/zh-TW/services/xbox-services/player-data/stats-leaderboards/title-managed/how-to/index.md)
- [取得遊戲管理型成就](/zh-TW/services/xbox-services/player-data/achievements/title-managed/how-to/live-how-to-get-achievements.md)
- [遊戲管理型統計資料與排行榜](/zh-TW/services/xbox-services/player-data/stats-leaderboards/title-managed/live-statslb-tm-nav.md)
- [設定遊戲管理型統計資料與排行榜](/zh-TW/services/xbox-services/player-data/stats-leaderboards/title-managed/config/live-tm-leaderboards-portal.md)