Sanctions Web APIs

通过惩罚Web API和RESTful服务来使用惩罚接口功能。

阅读时间20分钟

Epic 在线服务（EOS） 惩罚接口可以管理对你的用户采取的惩罚措施。惩罚可能包括临时或永久禁止游戏，禁止通信以及限制特定用户使用产品社交功能的其他措施。你可以根据自己的用例为产品定立惩罚，用来处理不良行为。

你可以使用惩罚 Web API 为受信任服务器应用程序的 EOS C SDK 提供补充。在调用惩罚 Web API 之前，请查看Web API 概述中规定的标准、身份验证和错误代码。

API 端点

https://api.epicgames.dev/sanctions/

查询特定玩家的有效惩罚

策略

使用的客户端策略必须允许 sanctions:findActiveSanctionsForAnyUser 操作。

授权

此调用要求使用从连接接口获取的 EOS 客户端身份验证访问令牌来进行 Bearer 令牌授权。

请求

HTTP 请求	`GET /sanctions/v1/productUser/{ProductUserId}/active`
HTTP 标头
名称	值
`授权`	`Bearer <EOSAccessToken>`
`内容类型`	`application/json`
路径参数
名称	类型	说明	必需
`ProductUserId`	字符串	用于查询惩罚的 EOS `ProductUserId`	是
查询参数
名称	类型	说明	必需
`操作`	字符串	可选操作筛选器。支持多个值：action=action1&action=action2 最大项目数：5	否

示例请求

响应

HTTP 响应 200 - OK：成功。
HTTP 标头
名称		值
`内容类型`		`application/json`
JSON 负载
名称	类型	说明
`元素`	数组<CompactSanction>	有效惩罚清单

CompactSanction

CompactSanction
名称	类型	说明
`referenceId`	字符串	此惩罚的唯一标识符
`timestamp`	int64	实施此惩罚时的纪元时间戳（以秒为单位）
`操作`	字符串	与此惩罚关联的操作字符串
`expirationTimestamp`	int64	此期限到期时的纪元时间戳（以秒为单位），如果惩罚是永久性的，则为null

将惩罚同步到外部服务

策略

使用的客户端策略必须允许 Sanctions:syncSanctionEvents 操作。

授权

此调用要求使用从连接接口获取的 EOS 客户端身份验证访问令牌来进行 Bearer 令牌授权。

请求

HTTP 请求	`GET /sanctions/v1/sync`
HTTP 标头
名称	值
`授权`	`Bearer <EOSAccessToken>`
`内容类型`	`application/json`
查询参数
名称	类型	说明	必需
`lastLogId`	字符串	上一次调用中处理的最后一个惩罚事件条目的可选ID。	否

示例请求

响应

HTTP 响应 200 - OK：成功。
HTTP 标头
名称		值
`内容类型`		`application/json`
JSON 负载
名称	类型	说明
元素	数组<SanctionEvent>	惩罚事件清单

SanctionEvent

SanctionEvent
名称	类型	说明
`productUserId`	字符串	受惩罚用户的EOS `ProductUserId`
`操作`	字符串	与此惩罚关联的操作字符串
`理由`	字符串	与此惩罚关联的理由字符串
`来源`	字符串	创建此惩罚的来源，例如“开发人员门户”
`eventType`	整型	`1`: 惩罚已创建 `2`: 惩罚已更新 `3`: 惩罚已删除
`标签`	数组<String>	与此惩罚关联的标签列表
`logId`	字符串	SanctionEvent日志条目的唯一标识符。此值可用于从同步API请求增量更新。
`referenceId`	字符串	此惩罚的唯一标识符
`timestamp`	字符串	实施此惩罚的时间
`expirationTimestamp`	字符串	此期限到期的时间，如果惩罚是永久性的，则为null
`batchUuid`	字符串	此惩罚关联请求的UUID。一个请求可能会批量创建多个惩罚。
`epicAccountName`	字符串	实施此惩罚的Epic Games账号的名称
`epicAccountId`	字符串	实施此惩罚的Epic Games账号的ID
`eosClientId`	字符串	用于实施此惩罚的客户端凭证ID
`eosClientRole`	字符串	用于实施此惩罚的客户端凭证角色
`createdAt`	字符串	惩罚服务后端收到此惩罚请求的时间
`updatedAt`	字符串	更新此惩罚的时间
`trustedPartner`	字符串	代表开发人员实施此惩罚的可信赖合作伙伴
`deploymentId`	字符串	此惩罚适用的EOS `DeploymentId`
`待定`	布尔值	如果此惩罚当前待定，则为`True`
`已自动化`	布尔值	如果此惩罚通过开发人员门户网站中的手动操作以外的方法创建，则为`True`
`元数据`	SanctionMetadata	与此惩罚关联的任意元数据键/值对
`displayName`	字符串	受惩罚用户的显示名称
`identityProvider`	字符串	受惩罚用户用以验证身份的身份提供商
`accountId`	字符串	具有指定identityProvider的受惩罚用户的账户ID
`修改`	SanctionModification	与惩罚更新关联的修改列表。该字段仅在`eventType`为`2`时设置。

SanctionMetadata

SanctionMetadata
名称	类型	说明
...	...	元数据键/值对。最大项目数：25。项目键最大长度：64。项目值最大长度：128。

SanctionModification

SanctionModification
名称	类型	说明
`updated_at`	字符串	进行此修改的时间
...	...	来自SanctionEvent的附加键/值对，指示更新中的更改

批量查询多个玩家的有效惩罚

策略

使用的客户端策略必须允许以下操作之一：

sanctions:findActiveSanctionsForAnyUser
sanctions:findSanctionsForAnyUser
sanctions:findAllSanctions
sanctions:syncSanctionEvents

授权

此调用要求使用从连接接口获取的 EOS 客户端身份验证访问令牌来进行 Bearer 令牌授权。

请求

HTTP 请求	`GET /sanctions/v1/{deploymentId}/active-sanctions`
HTTP 标头
名称	值
`授权`	`Bearer <EOSAccessToken>`
`内容类型`	`application/json`
路径参数
名称	类型	说明	必需
`deploymentId`	字符串	要查询的`deploymentId`	是
查询参数
名称	类型	说明	必需
`productUserId`	字符串	所需的产品用户ID筛选器。支持多个值： `productUserId=productUserId1&productUserId=productUserId2`。最大项目数：100	是
`操作`	字符串	所需的操作筛选器。支持多个值：`action=action1&action=action2` 最大项目数：5	是

示例请求

响应

HTTP 响应 200 - OK：成功。
HTTP 标头
名称		值
`内容类型`		`application/json`
JSON 负载
名称	类型	说明
元素	数组<CompactSanctionWithPuid>	有效惩罚清单

CompactSanctionWithPuid

CompactSanctionWithPuid
名称	类型	说明
`productUserId`	字符串	产品用户ID
`referenceId`	字符串	此惩罚的唯一标识符
`timestamp`	字符串	实施此惩罚的时间，采用ISO 8601格式
`操作`	字符串	与此惩罚关联的操作字符串
`expirationTimestamp`	字符串	此期限到期的时间，采用ISO 8601格式，如果惩罚是永久性的，则为null

示例响应

创建惩罚

策略

使用的客户端策略必须允许 sanctions:createSanction 操作。

授权

此调用要求使用从连接接口获取的 EOS 客户端身份验证访问令牌来进行 Bearer 令牌授权。

请求

HTTP 请求	`POST /sanctions/v1/{deploymentId}/sanctions`
HTTP 标头
名称	值
`授权`	`Bearer <EOSAccessToken>`
`内容类型`	`application/json`
路径参数
名称	类型	说明	必需
`deploymentId`	字符串	要查询的`deploymentId`	是
JSON 负载
类型	说明
`数组<SanctionPostPayload>`	要创建的惩罚列表

示例请求

SanctionPostPayload

SanctionPostPayload
名称	类型	说明	必需
`productUserId`	字符串	受惩罚用户的EOS `ProductUserId`	是
`操作`	字符串	与此惩罚关联的操作字符串。格式：[a-zA-Z0-9_-]+。最小长度：1。最大长度：64。	是
`理由`	字符串	与此惩罚关联的理由字符串。最小长度：1 最大长度：2048	是
`来源`	字符串	创建此惩罚的来源，例如“开发人员门户”。格式：`[a-zA-Z0-9_-]+`。最小长度：2。最大长度： 64。	是
`标签`	数组<String>	与此惩罚关联的标签列表。项目不区分大小写且具有唯一性。项目格式：`[a-zA-Z0-9_-]+`。项目最大长度：16	否
`待定`	布尔值	如果此惩罚当前待定，则为`True`	否
`元数据`	SanctionMetadata	与此惩罚关联的任意元数据键/值对	否
`displayName`	字符串	受惩罚用户的显示名称。最大长度：64	否
`identityProvider`	字符串	受惩罚用户用以验证身份的身份提供商。最大长度：64	否
`accountId`	字符串	具有指定identityProvider的受惩罚用户的账户ID。最大长度：64	否
`期限`	整型	惩罚时长（以秒为单位）	否

响应

HTTP 响应 200 - OK：成功。
HTTP 标头
名称		值
`内容类型`		`application/json`
JSON 负载
名称	类型	说明
`元素`	数组<Sanction>	已创建惩罚列表

Sanction

Sanction
名称	类型	说明
`productUserId`	字符串	受惩罚用户的EOS `ProductUserId`
`操作`	字符串	与此惩罚关联的操作字符串
`理由`	字符串	与此惩罚关联的理由字符串
`来源`	字符串	创建此惩罚的来源，例如“开发人员门户”
`标签`	数组<String>	与此惩罚关联的标签列表
`referenceId`	字符串	此惩罚的唯一标识符
`timestamp`	字符串	Time when this sanction was placed.
`expirationTimestamp`	字符串	此期限到期的时间，如果惩罚是永久性的，则为null
`batchUuid`	字符串	此惩罚关联请求的UUID。一个请求可能会批量创建多个惩罚。
`epicAccountName`	字符串	实施此惩罚的Epic Games账号的名称
`epicAccountId`	字符串	实施此惩罚的Epic Games账号的ID
`eosClientId`	字符串	用于实施此惩罚的客户端凭证ID
`eosClientRole`	字符串	用于实施此惩罚的客户端凭证角色
`createdAt`	字符串	惩罚服务后端收到此惩罚请求的时间。时间采用ISO 8601和RFC3339格式，比如： `2021-01-01T00:00:00.000Z`。
`updatedAt`	字符串	更新此惩罚的时间。时间采用ISO 8601和RFC3339格式，比如： `2021-01-01T00:00:00.000Z`。
`removedAt`	字符串	移除此惩罚的时间。时间采用ISO 8601和RFC3339格式，比如： `2021-01-01T00:00:00.000Z`。
`trustedPartner`	字符串	代表开发人员实施此惩罚的可信赖合作伙伴
`deploymentId`	字符串	此惩罚适用的EOS `DeploymentId`
`待定`	布尔值	如果此惩罚当前待定，则为`True`
`已自动化`	布尔值	如果此惩罚通过开发人员门户网站中的手动操作以外的方法创建，则为`True`
`元数据`	SanctionMetadata	与此惩罚关联的任意元数据键/值对
`displayName`	字符串	受惩罚用户的显示名称
`identityProvider`	字符串	受惩罚用户用以验证身份的身份提供商
`accountId`	字符串	具有指定identityProvider的受惩罚用户的账户ID
`status`	字符串	惩罚状态。包括活跃、待定、过期、移除

**注意：**时间采用ISO 8601和RFC3339格式。例如： 2021-01-01T00:00:00.000Z

示例响应

查询所有惩罚

策略

使用的客户端策略必须允许以下操作之一：

sanctions:findSanctionsForAnyUser
sanctions:findAllSanctions
sanctions:syncSanctionEvents

授权

此调用要求使用从连接接口获取的 EOS 客户端身份验证访问令牌来进行 Bearer 令牌授权。

请求

HTTP 请求	`GET /sanctions/v1/{deploymentId}/sanctions`
HTTP 标头
名称	值
`授权`	`Bearer <EOSAccessToken>`
`内容类型`	`application/json`
路径参数
名称	类型	说明	必需
`deploymentId`	字符串	要查询的`deploymentId`	是
查询参数
名称	类型	说明	必需
`限制`	整型	要返回的元素数。默认值`100`。	否
`偏移`	整型	要跳过的元素数。默认值`0`。	否

请求示例

响应

HTTP 响应 200 - OK：成功。
HTTP 标头
名称		值
`内容类型`		`application/json`
JSON 负载
名称	类型	说明
`元素`	数组<Sanction>	按createdAt降序排列的惩罚列表。
`分页`	Object<Paging>	分页信息

示例响应

查询玩家的所有惩罚

策略

使用的客户端策略必须允许以下操作之一：

sanctions:findSanctionsForAnyUser
sanctions:findSanctionsForLocalUser
sanctions:findAllSanctions
sanctions:syncSanctionEvents

授权

此调用要求使用从连接接口获取的 EOS 客户端身份验证访问令牌来进行 Bearer 令牌授权。

请求

HTTP 请求	`GET /sanctions/v1/{deploymentId}/users/{productUserId}`
HTTP 标头
名称	值
`授权`	`Bearer <EOSAccessToken>`
`内容类型`	`application/json`
路径参数
名称	类型	说明	必需
`deploymentId`	字符串	要查询的`deploymentId`	是
`productUserId`	字符串	要查询的`productUserId`	是
查询参数
名称	类型	说明	必需
`限制`	整型	要返回的元素数。默认值`100`。	否
`偏移`	整型	要跳过的元素数。默认值`0`。	否

示例请求

响应

HTTP 响应 200 - OK：成功。
HTTP 标头
名称		值
`内容类型`		`application/json`
JSON 负载
名称	类型	说明
`元素`	数组<Sanction>	按createdAt降序排列的惩罚列表。
`分页`	Object<Paging>	分页信息

示例响应

更新惩罚

策略

使用的客户端策略必须允许 sanctions:updateSanction 操作。

授权

此调用要求使用从连接接口获取的 EOS 客户端身份验证访问令牌来进行 Bearer 令牌授权。

请求

HTTP 请求	`PATCH /sanctions/v1/{deploymentId}/sanctions`
HTTP 标头
名称	值
`授权`	`Bearer <EOSAccessToken>`
`内容类型`	`application/json`
路径参数
名称	类型	说明	必需
`deploymentId`	字符串	要查询的`deploymentId`	是
JSON 负载
类型	说明
`数组<SanctionPatchPayload>`	适用的惩罚更新列表

示例请求

SanctionPatchPayload

SanctionPatchPayload
名称	类型	说明	必需
`referenceId`	字符串	此惩罚的唯一标识符	是
`更新`	UpdatableFields	要更新的字段及其新值。	是

UpdatableFields

UpdatableFields
名称	类型	说明	必需
`标签`	数组<String>	与此惩罚关联的标签列表。项目不区分大小写且具有唯一性。项目格式：[a-zA-Z0-9_-]+。项目最大长度：16	否
`元数据`	SanctionMetadata	与此惩罚关联的任意元数据键/值对	否
`理由`	字符串	与此惩罚关联的理由字符串。最小长度：1 最大长度：2048	否

响应

HTTP 响应 200 - OK：成功。
HTTP 标头
名称		值
`内容类型`		`application/json`
JSON 负载
名称	类型	说明
`元素`	数组<Sanction>	已更新惩罚列表

示例响应

取消惩罚

策略

使用的客户端策略必须允许 sanctions:deleteSanction 操作。

授权

此调用要求使用从连接接口获取的 EOS 客户端身份验证访问令牌来进行 Bearer 令牌授权。

请求

HTTP 请求	`DELETE /sanctions/v1/{deploymentId}/sanctions`
HTTP 标头
名称	值
`授权`	`Bearer <EOSAccessToken>`
`内容类型`	`application/json`
路径参数
名称	类型	说明	必需
`deploymentId`	字符串	要查询的`deploymentId`	是
JSON 负载
类型	说明
`SanctionDeletePayload`	要删除的惩罚及理由

请求示例

SanctionDeletePayload

SanctionDeletePayload
名称	类型	说明	必需
`referenceIds`	数组<String>	要取消惩罚的唯一标识符	是
`理由`	字符串	与取消此惩罚关联的理由字符串。最小长度：1 最大长度：2048	否

响应

HTTP 响应 204 - 没有内容。

Paging

分页
名称	类型	说明
`偏移`	整型	分页偏移
`限制`	整型	每次调用返回的惩罚数量
`总计`	整型	惩罚总数

创建惩罚申诉

策略

使用的客户端策略必须允许 sanctions:createAppealsForAnyUser 操作。

授权

此调用要求 EOS 客户端身份验证访问令牌来进行 Bearer 令牌授权。

请求

HTTP 请求	`POST /sanctions/v1/{deploymentId}/appeals`
HTTP 标头
名称	值
`授权`	`Bearer <EOSAccessToken>`
`内容类型`	`application/json`
路径参数
名称	类型	说明	必需
`deploymentId`	字符串	要查询的`deploymentId`	是
JSON 负载
类型	说明
`AppealPostPayload`	惩罚申诉负载

示例请求

AppealPostPayload

AppealPostPayload
名称	类型	说明	必需
`referenceId`	字符串	要申诉的惩罚的唯一标识符。	是
`原因`	整型	申诉原因数字代码。 `1`：错误惩罚。 `2`: 账号被盗。 `3`: 不公平惩罚。 `4`: 申请原谅。	是

响应

HTTP 响应 200 - OK：成功。
HTTP 标头
名称		值
内容类型		`application/json`
JSON 负载
类型	说明
申诉	创建的申诉

Appeal

Appeal
名称	类型	说明
`id`	字符串	申诉的唯一标识符。
`状态`	字符串	申诉的状态
`referenceId`	字符串	要申诉的惩罚的唯一标识符。
`createdAt`	字符串	申诉请求创建的时间。时间采用ISO 8601和RFC3339格式。例如： `2021-01-01T00:00:00.000Z`
`updatedAt`	字符串	申诉更新的时间。时间采用ISO 8601和RFC3339格式。例如： `2021-01-01T00:00:00.000Z`
`原因`	整型	申诉的原因数字代码。

示例响应

查询惩罚

策略

使用的客户端策略必须允许 sanctions:findAppealsForAnyUser 操作。

授权

此调用要求 EOS 客户端身份验证访问令牌来进行 Bearer 令牌授权。

请求

HTTP 请求	`GET /sanctions/v1/{deploymentId}/appeals`
HTTP 标头
名称	值
`授权`	`Bearer <EOSAccessToken>`
`内容类型`	`application/json`
路径参数
名称	类型	说明	必需
`deploymentId`	字符串	要查询的`deploymentId`	是
查询参数
名称	类型	说明	必需
`限制`	整型	要返回的元素数。默认值`100`。	否
`偏移`	整型	要跳过的元素数。默认值`0`。	否
`referenceId`	字符串	惩罚标识符筛选器。可以使用多个。	否
`status`	字符串	申诉状态筛选器。可以使用多个。	否
`productUserId`	字符串	产品用户ID 筛选器。可以使用多个。	否

示例请求

响应

HTTP 响应 200 - OK：成功。
HTTP 标头
名称		值
`内容类型`		`application/json`
JSON 负载
名称	类型	说明
`元素`	数组<Appeal>	按createdAt 降序排列的申诉列表。
`分页`	Object<Paging>	分页信息