取得好友排行榜

Retrieves a list of ranked friends of the given player for the given statistic, starting from the indicated point in the leaderboard

Error codes

This operation may return the following PlayFab errors:

Error	Code
ExpiredXboxLiveToken	1189
FacebookAPIError	1143
InvalidXboxLiveToken	1188
LeaderboardVersionNotAvailable	1277
ProductDisabledForTitle	1609
XboxInaccessible	1339
XboxServiceTooManyRequests	1505
XboxXASSExchangeFailure	1306

POST

Server

GetFriendLeaderboard

Get Friend Leaderboard

curl --request POST \
  --url https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard \
  --header 'Content-Type: application/json' \
  --header 'X-SecretKey: <api-key>' \
  --data '
{
  "PlayFabId": "98092347523",
  "StatisticName": "Kills",
  "StartPosition": 1258,
  "MaxResultsCount": 20,
  "ExternalPlatformFriends": "None"
}
'

import requests

url = "https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard"

payload = {
    "PlayFabId": "98092347523",
    "StatisticName": "Kills",
    "StartPosition": 1258,
    "MaxResultsCount": 20,
    "ExternalPlatformFriends": "None"
}
headers = {
    "X-SecretKey": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-SecretKey': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    PlayFabId: '98092347523',
    StatisticName: 'Kills',
    StartPosition: 1258,
    MaxResultsCount: 20,
    ExternalPlatformFriends: 'None'
  })
};

fetch('https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'PlayFabId' => '98092347523',
    'StatisticName' => 'Kills',
    'StartPosition' => 1258,
    'MaxResultsCount' => 20,
    'ExternalPlatformFriends' => 'None'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-SecretKey: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard"

	payload := strings.NewReader("{\n  \"PlayFabId\": \"98092347523\",\n  \"StatisticName\": \"Kills\",\n  \"StartPosition\": 1258,\n  \"MaxResultsCount\": 20,\n  \"ExternalPlatformFriends\": \"None\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-SecretKey", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard")
  .header("X-SecretKey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"PlayFabId\": \"98092347523\",\n  \"StatisticName\": \"Kills\",\n  \"StartPosition\": 1258,\n  \"MaxResultsCount\": 20,\n  \"ExternalPlatformFriends\": \"None\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-SecretKey"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"PlayFabId\": \"98092347523\",\n  \"StatisticName\": \"Kills\",\n  \"StartPosition\": 1258,\n  \"MaxResultsCount\": 20,\n  \"ExternalPlatformFriends\": \"None\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "Leaderboard": [
      {
        "PlayFabId": "10931252888739651331",
        "DisplayName": "username",
        "StatValue": 12,
        "Profile": {
          "AvatarUrl": "https://example.org/profile.jpg",
          "Statistics": [
            {
              "Name": "Points",
              "Version": 2,
              "Value": 15
            },
            {
              "Name": "XP",
              "Version": 1,
              "Value": 10
            }
          ]
        }
      }
    ]
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

授權

X-SecretKey

string

header

必填

This API requires a title secret key, available to title admins, from PlayFab Game Manager.

主體

application/json

MaxResultsCount

number

必填

Maximum number of entries to retrieve.

PlayFabId

string

必填

The player whose friend leaderboard to get

StartPosition

number

必填

Position in the leaderboard to start this listing (defaults to the first entry).

StatisticName

string

必填

Statistic used to rank friends for this leaderboard.

CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

ExternalPlatformFriends

enum<string>

Indicates which other platforms' friends should be included in the response. In HTTP, it is represented as a comma-separated list of platforms.

可用選項:

None,

Steam,

Facebook,

Xbox,

Psn,

All

ProfileConstraints

object

If non-null, this determines which properties of the resulting player profiles to return. For API calls from the client, only the allowed client profile properties for the title may be requested. These allowed properties are configured in the Game Manager "Client Profile Options" tab in the "Settings" section.

Show child attributes

UseSpecificVersion

boolean

If set to false, Version is considered null. If true, uses the specified Version

Version

number

The version of the leaderboard to get.

XboxToken

string

Xbox token if Xbox friends should be included. Requires Xbox be configured on PlayFab.

回應

Note that the Position of the user in the results is for the overall leaderboard.

code

integer

The Http status code. If X-ReportErrorAsSuccess header is set to true, this will report the actual http error code.

status

string

The Http status code as a string.

data

object

Note that the Position of the user in the results is for the overall leaderboard.

Show child attributes

範例:

{
  "Leaderboard": [
    {
      "PlayFabId": "10931252888739651331",
      "DisplayName": "username",
      "StatValue": 12,
      "Profile": {
        "AvatarUrl": "https://example.org/profile.jpg",
        "Statistics": [
          {
            "Name": "Points",
            "Version": 2,
            "Value": 15
          },
          { "Name": "XP", "Version": 1, "Value": 10 }
        ]
      }
    }
  ]
}

最後修改於 2026年10月6日

⌘I

Get Friend Leaderboard

curl --request POST \
  --url https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard \
  --header 'Content-Type: application/json' \
  --header 'X-SecretKey: <api-key>' \
  --data '
{
  "PlayFabId": "98092347523",
  "StatisticName": "Kills",
  "StartPosition": 1258,
  "MaxResultsCount": 20,
  "ExternalPlatformFriends": "None"
}
'

import requests

url = "https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard"

payload = {
    "PlayFabId": "98092347523",
    "StatisticName": "Kills",
    "StartPosition": 1258,
    "MaxResultsCount": 20,
    "ExternalPlatformFriends": "None"
}
headers = {
    "X-SecretKey": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-SecretKey': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    PlayFabId: '98092347523',
    StatisticName: 'Kills',
    StartPosition: 1258,
    MaxResultsCount: 20,
    ExternalPlatformFriends: 'None'
  })
};

fetch('https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'PlayFabId' => '98092347523',
    'StatisticName' => 'Kills',
    'StartPosition' => 1258,
    'MaxResultsCount' => 20,
    'ExternalPlatformFriends' => 'None'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-SecretKey: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard"

	payload := strings.NewReader("{\n  \"PlayFabId\": \"98092347523\",\n  \"StatisticName\": \"Kills\",\n  \"StartPosition\": 1258,\n  \"MaxResultsCount\": 20,\n  \"ExternalPlatformFriends\": \"None\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-SecretKey", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard")
  .header("X-SecretKey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"PlayFabId\": \"98092347523\",\n  \"StatisticName\": \"Kills\",\n  \"StartPosition\": 1258,\n  \"MaxResultsCount\": 20,\n  \"ExternalPlatformFriends\": \"None\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Server/GetFriendLeaderboard")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-SecretKey"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"PlayFabId\": \"98092347523\",\n  \"StatisticName\": \"Kills\",\n  \"StartPosition\": 1258,\n  \"MaxResultsCount\": 20,\n  \"ExternalPlatformFriends\": \"None\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "Leaderboard": [
      {
        "PlayFabId": "10931252888739651331",
        "DisplayName": "username",
        "StatValue": 12,
        "Profile": {
          "AvatarUrl": "https://example.org/profile.jpg",
          "Statistics": [
            {
              "Name": "Points",
              "Version": 2,
              "Value": 15
            },
            {
              "Name": "XP",
              "Version": 1,
              "Value": 10
            }
          ]
        }
      }
    ]
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

PlayFab API

PlayFab REST API References

取得好友排行榜

Error codes

授權

主體

回應