开发
开发
选择平台

排行榜服务器 API

更新时间: 2024年7月24日
服务器到服务器 (S2S) Rest API 提供了安全的渠道，用来与 Meta Horizon 平台进行互动。例如，您可能想要在服务器上举办多人比赛后更新 Meta 排行榜。本文将介绍您可以执行的排行榜相关服务器调用的详情。

消息基础知识

您应该了解一些关于服务器到服务器消息的基础知识。

服务器到服务器 API 要求

调用这些 API 必须满足以下要求：

端点

将所有服务器到服务器的请求发送到此端点：
https://graph.oculus.com

访问口令

在每个请求中包含一个访问口令，将其作为有效的服务器请求或代表特定用户进行验证。访问口令可以是以下任何一项：

应用凭证

应用凭证将您的服务器后端验证为可信资源。切勿与任何客户端应用程序分享这些凭证。
带有应用凭证的访问口令包括 Meta Horizon 开发者面板上的 API⁠ 页面中的应用编号和应用密钥。其格式如下：OC|$APPID|$APPSECRET。
如果您的凭证泄露或者需要新的 API 凭证，则可以生成新的应用密钥。更改应用密钥将撤销前一个密钥的权限。访问应用密钥需要管理员账户。

用户访问口令

用户访问口令代表用户验证请求。当操作与特定用户相关时，使用此口令类型。一个示例是使用服务器托管的多人游戏比赛结果更新客户端权威排行榜。对于每个用户，当您请求更新排行榜时，您将使用用户访问口令向服务器进行身份验证。
使用 ovr_User_GetAccessToken() 方法检索用户口令。
口令会作为响应返回，并可从客户端传递到服务器。用户访问口令包含 FRL 或 OC，以及类似 FRL12342GhFccWvUBxPMR4KXzM5s2ZCMp0mlWGq0ZBrOMXyjh4EmuAPvaXiMCAMV9okNm9DXdUA2EWNplrQ 的长字母数字字符串。
此外，您可以前往 Meta Horizon 开发者面板的 API⁠ 页面，进入左侧导航栏的“用户口令”版块，检索您的用户口令以进行测试。

应用编号

有些服务器调用需要一个应用编号，您可以在 Meta Horizon 开发者面板的 API⁠ 页面找到这个编号。
注意：cURL 示例展示如何通过 Windows 命令行执行调用。其他平台的操作可能有所不同。

创建或更新排行榜

使用此方法创建排行榜，或更新现有排行榜的属性。您可以使用此方法指定或更新排行榜的本地化显示标题。更多详情请参阅 title_locale_map 参数。
注意：任何人都可以检索排行榜元数据。在创建或更新排行榜时，避免存储敏感信息。
网址：https://graph.oculus.com/{app_id}/leaderboards
方法：POST
请求示例：
POST /1234757621998335/leaderboards/?api_name=best_leaderboard&sort_order=HIGHER_IS_BETTER&entry_write_policy=CLIENT_AUTHORITATIVE&title_locale_map={"en_US":"Soccer", "en_GB":"Football"}
HTTP/1.1
Host: graph.oculus.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
cURL 请求示例：
curl -d "access_token=OC|$APP_ID|$APP_SECRET" -d "api_name=best_leaderboard" -d "sort_order=HIGHER_IS_BETTER" -d "title_locale_map={\"en_US\":\"Soccer\", \"en_GB\":\"Football\"}" -d "entry_write_policy=CLIENT_AUTHORITATIVE" -d "earliest_allowed_entry_time=1463875200" -d "latest_allowed_entry_time=1964480000" https://graph.oculus.com/$APP_ID/leaderboards"
参数：
响应示例：
{"id":"10742336355960170"}

创建或更新排行榜条目

使用此方法创建排行榜条目，或更新现有条目。如要调用此方法，您应该：
  • 如果排行榜是客户端主导的，应使用用户口令对调用进行身份验证，并且不用提供用户编号。
  • 如果排行榜是服务器主导的，应使用应用口令对调用进行身份验证。提供应用口令时，您还必须提供用户编号。
网址：https://graph.oculus.com/leaderboard_submit_entry
方法：POST
请求示例（服务器主导）：

POST /leaderboard_submit_entry/?api_name=best_leaderboard&score=12345&extra_data_base64=T271bHVz&force_update=true&user_id=123402235207175
HTTP/1.1
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
cURL 请求示例（客户端主导）：
curl -d "access_token=<user access token>" -d "api_name=best_leaderboard" -d "score=12345" -d "extra_data_base64=T271bHVz" -d "force_update=true" https://graph.oculus.com/leaderboard_submit_entry
参数：
响应示例：
响应包含状态 did_update，表明该条目是否被记录。如果用户在排行榜上已有条目，且新分数低于旧分数，并且 force_update 为 false，则条目将不会被记录。
{"did_update":true,"updated_challenge_ids":[],"success":true}

检索应用中的排行榜数据

使用此方法获取排行榜的条目数量、写入策略和排序顺序。
网址：https://graph.oculus.com/{app_id}/leaderboards
方法：GET
请求示例：
GET /12347576219/leaderboards/?api_name=best_leaderboard
 &fields=sort_order,entry_write_policy,entry_count
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
cURL 请求示例：
curl -G -d "access_token=OC|$APP_ID|$APP_SECRET" -d "fields=sort_order,entry_write_policy,entry_count" https://graph.oculus.com/$APP_ID/leaderboards
参数：
响应示例：
{
    "data": [
        {
          "id": "1074273245960170",
          "sort_order": "HIGHER_IS_BETTER",
          "entry_write_policy": "CLIENT_AUTHORITATIVE",
          "entry_count": 2500
        },
        {...}
    ]
}

检索排行榜条目

您可以检索用户的排行榜条目，包括用户编号、别名和个人主页网址，以及排行榜排名、条目数量等信息。如要调用此方法，您应该：
  • 如果 start_at 参数的值是 VIEWER 的选项之一，应使用用户口令对调用进行身份验证。
  • 如果 filter 参数的值是 FRIENDS，应使用用户口令对调用进行身份验证。
  • 否则，应使用应用口令对调用进行身份验证。
网址：https://graph.oculus.com/leaderboard_entries
方法：GET
请求示例：
GET /leaderboard_entries/?api_name=best_leaderboard&fields=user{id, alias, profile_url}, rank, score, timestamp, extra_data_base64&filter=NONE&start_at=OFFSET&offset=10&summary=true&limit=2
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
cURL 请求示例：
curl -G https://graph.oculus.com/leaderboard_entries -d "access_token=$ACCESS_TOKEN" -d "api_name=best_leaderboard" -d "filter=NONE" -d "start_at=OFFSET" -d "offset=0" -d "summary=true" -d "limit=2" -d "fields=user{id,alias,profile_url},rank,score,timestamp,extra_data_base64"
参数：
响应示例：
{
    "data": [{
        "id": "1074233745529170",
        "user": {
            "id": "865307770207175",
            "alias": "UnknownXuid",
            "profile_url": "someUrl",
            "rank": 25,
            "score": 12345,
            "timestamp": 1456523020,
            "extra_data_base64": "T2N1bHVz"
        }
    }],
    "summary": {
        "total_count": 45
    },
    "paging": {
        "next": "...",
        "previous": "..."
    }
}
上述响应中返回的第一个编号是条目编号，可以引用该编号并将其用于删除用户的排行榜条目。

获取应用中的所有排行榜

获取应用中的所有排行榜，包括非公开的部分。
https://graph.oculus.com/{app_id}/leaderboards
方法：GET
请求示例：
GET /1234757621998335/leaderboards/
HTTP/1.1
Host: graph.oculus.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
cURL 请求示例：
curl -G https://graph.oculus.com/$APP_ID/leaderboards -d "access_token=OC|$APP_ID|$APP_SECRET"
参数：
响应示例：
{"data":[{"id":"3123283331082594"},{"id":"3063603433693729"},{"id":"3076319039125567"}]}

删除单一用户的排行榜条目

使用此方法，通过指定 entry-id 来删除单一条目。检索排行榜条目请求会返回 entry-id。
网址：https://graph.oculus.com/{entry_id}
方法：DELETE
请求示例：
DELETE /12345 HTTP/1.1
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
cURL 请求示例：
curl -X DELETE -d "access_token=OC|$APP_ID|$APP_SECRET" https://graph.oculus.com/$LEADERBOARD_ENTRY_ID
参数：
响应示例：
{"success":true}

删除所有排行榜条目

删除排行榜中的所有条目。此操作无法恢复。
网址：https://graph.oculus.com/leaderboard_remove_all_entries
方法：POST
请求示例：
POST /leaderboard_remove_all_entries?api_name=MY_NEW_LEADERBOARD
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
cURL 请求示例：
curl -d "access_token=OC|$APP_ID|$APP_SECRET" -d "api_name=MY_NEW_LEADERBOARD" https://graph.oculus.com/leaderboard_remove_all_entries
参数：
响应示例：
{"success":true}

删除排行榜

删除排行榜。创建或更新排行榜请求会返回 leaderboard-id 编号。排行榜条目一经删除将无法恢复。
网址：https://graph.oculus.com/leaderboard_id
方法：DELETE
请求示例：
DELETE /12345567893
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

curl -X "DELETE" -d "access_token=OC|$APP_ID|$APP_SECRET" https://graph.oculus.com/12345567893
参数：
响应示例：
{"success":true}

疑难解答

已按照 cURL 请求示例操作，但 REST API 无法正常工作，该怎么办？
首先，您要仔细检查 access_token 是否已正确设置。在一些请求中，其值应是 OC|$APP_ID|$APP_SECRET，而在一些请求中，其值是用户访问口令。
如果您使用 cURL 命令访问 API，请确保使用反斜杠来转义双引号和方括号之类的字符。
如果您的 cURL 命令包含类似 offset 或允许的时间戳之类的数据字段，就需要确保设置的值与您的查询一致，否则将不会返回结果。
导航徽标
虚拟现实 / Meta Horizon
虚拟现实 / Meta Horizon
虚拟现实 / Meta Horizon
中文(简体)
© 2026 Meta