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

# GET (/users/xuid({xuid})/achievements)

> GET (/users/xuid({xuid})/achievements)

# GET (/users/xuid({xuid})/achievements)

获取标题上定义的成就列表、用户已解锁的成就或用户正在进行中的成就。
这些 URI 的域为 `achievements.xboxlive.com`。

* [URI 参数](#ID4EX)
* [查询字符串参数](#ID4ECB)
* [授权](#ID4ENF)
* [必需的请求标头](#ID4ESG)
* [可选的请求标头](#ID4ESH)
* [请求正文](#ID4EIBAC)
* [响应正文](#ID4ETBAC)

## URI 参数

| 参数 | 类型 | 说明 |
| - | - | - |
| xuid | 64 位无符号整数 | 正在访问其(资源)的用户的 XBOX User ID (XUID)。必须与已认证用户的 XUID 匹配。 |

## 查询字符串参数

| 参数 | 是否必需 | 类型 | 说明 |
| - | - | - | - |
| **skipItems** | 否 | 32 位有符号整数 | 从给定项数之后开始返回项。例如,**skipItems="3"** 将检索从第四项开始的项。 |
| **continuationToken** | 否 | string | 从给定的续传令牌开始返回项。 |
| **maxItems** | 否 | 32 位有符号整数 | 从集合中返回的最大项数,可与 **skipItems** 和 **continuationToken** 组合使用以返回一定范围的项。如果没有提供 **maxItems**,服务可能会提供默认值,并且即使尚未返回最后一页结果,也可能返回少于 **maxItems** 的项。 |
| **titleId** | 否 | string | 用于所返回结果的筛选器。接受一个或多个以逗号分隔的十进制标题标识符。 |
| **unlockedOnly** | 否 | 布尔值 | 用于所返回结果的筛选器。如果设置为 **true**,将仅返回用户已解锁的成就。默认为 **false**。 |
| **possibleOnly** | 否 | 布尔值 | 用于所返回结果的筛选器。如果设置为 **true**,将返回所有可能的结果,但不返回已解锁的元数据 - 仅返回来自 XMS 的成就信息。默认为 **false**。 |
| **types** | 否 | string | 用于所返回结果的筛选器。可以为 "Persistent" 或 "Challenge"。默认为所有受支持的类型。 |
| **orderBy** | 否 | string | 指定返回结果的顺序。可以为 "Unordered"、"Title"、"UnlockTime" 或 "EndingSoon"。默认为 "Unordered"。 |

## 授权

| 声明 | 是否必需? | 说明 | 缺失时的行为 |
| - | - | - | - |
| User | 调用者是已授权的 XBOX LIVE 用户。 | 调用者必须是 XBOX LIVE 上的有效用户。 | 403 Forbidden |

## 必需的请求标头

| 标头 | 类型 | 说明 |
| - | - | - |
| Authorization | string | 用于 HTTP 身份验证的凭据。示例值:"XBL3.0 x=\<userhash>;\<token>"。 |

## 可选的请求标头

| 标头 | 类型 | 说明 |
| - | - | - |
| **X-RequestedServiceVersion** | string | 此请求应发送到的 XBOX LIVE 服务的生成名称/编号。仅在验证标头的有效性、认证令牌中的声明等之后,请求才会被路由到该服务。默认值:1。 |
| **x-xbl-contract-version** | 32 位无符号整数 | 如果存在且设置为 2,则将使用此 API 的 V2 版本。否则,使用 V1。 |
| **Accept-Language** | string | 所需区域设置和回退项的列表(例如,fr-FR、fr、en-GB、en-WW、en-US)。成就服务将逐个检查该列表,直到找到匹配的本地化字符串。如果未找到,则尝试匹配用户令牌中定义的位置,该位置来自用户的 IP 地址。如果仍未找到匹配的本地化字符串,则使用标题开发者/发行商提供的默认字符串。 |

## 请求正文

此请求的正文中不发送任何对象。

## 响应正文

如果调用成功,服务将返回 [Achievement (JSON)](https://devdocs.xbox.com/zh-CN/reference/live/rest/json/json-achievementv2) 对象数组和 [PagingInfo (JSON)](https://devdocs.xbox.com/zh-CN/reference/live/rest/json/json-paginginfo) 对象。

### 响应示例

```cpp theme={null}
{
    "achievements":
    [{
        "id":"3",
        "serviceConfigId":"b5dd9daf-0000-0000-0000-000000000000",
        "name":"Default NameString for Microsoft Achievements Sample Achievement 3",
        "titleAssociations":
        [{
                "name":"Microsoft Achievements Sample",
                "id":3051199919,
                "version":"abc"
        }],
        "progressState":"Achieved",
        "progression":
        {
                "achievementState":"Achieved",
                "requirements":null,
                "timeUnlocked":"2013-01-17T03:19:00.3087016Z",
        },
        "mediaAssets":
        [{
                "name":"Icon Name",
                "type":"Icon",
                "url":"http://www.xbox.com"
        }],
        "platform":"D",
        "isSecret":true,
        "description":"Default DescriptionString for Microsoft Achievements Sample Achievement 3",
        "lockedDescription":"Default UnachievedString for Microsoft Achievements Sample Achievement 3",
        "productId":"12345678-1234-1234-1234-123456789012",
        "achievementType":"Challenge",
        "participationType":"Individual",
        "timeWindow":
        {
                "startDate":"2013-02-01T00:00:00Z",
                "endDate":"2100-07-01T00:00:00Z"
        },
        "rewards":
        [{
                "name":null,
                "description":null,
                "value":"10",
                "type":"Gamerscore",
                "valueType":"Int"
        },
        {
                "name":"Default Name for InAppReward for Microsoft Achievements Sample Achievement 3",
                "description":"Default Description for InAppReward for Microsoft Achievements Sample Achievement 3",
                "value":"1",
                "type":"InApp",
                "valueType":"String"
        }],
        "estimatedTime":"06:12:14",
        "deeplink":"aWFtYWRlZXBsaW5r",
        "isRevoked":false
        }],
        "pagingInfo":
        {
                "continuationToken":null,
                "totalRecords":1
        }
}
         
```

## 另请参阅

##### 父主题

[/users/xuid({xuid})/achievements](https://devdocs.xbox.com/zh-CN/reference/live/rest/uri/achievements/uri-achievementsusersxuidachievementsv2)

##### 参考

[Achievement (JSON)](https://devdocs.xbox.com/zh-CN/reference/live/rest/json/json-achievementv2)

[PagingInfo (JSON)](https://devdocs.xbox.com/zh-CN/reference/live/rest/json/json-paginginfo)

[分页参数](https://devdocs.xbox.com/zh-CN/reference/live/rest/additional/pagingparameters)


## Related topics

- [XblAchievementsGetAchievementAsync](https://devdocs.xbox.com/fr/reference/live/xsapi-c/achievements_c/functions/xblachievementsgetachievementasync.md)
- [XblAchievementsGetAchievementsForTitleIdAsync](https://devdocs.xbox.com/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsgetachievementsfortitleidasync.md)