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筛选器。支持多个值:
| 是 |
操作 |
字符串 | 所需的操作筛选器。支持多个值: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 | 是 |
来源 |
字符串 | 创建此惩罚的来源,例如“开发人员门户”。格式: | 是 |
标签 |
数组<String> | 与此惩罚关联的标签列表。项目不区分大小写且具有唯一性。 项目格式: | 否 |
待定 |
布尔值 | 如果此惩罚当前待定,则为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 请求 |
| ||
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> | 分页信息 |