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 与惩罚更新关联的修改列表。该字段仅在eventType2时设置。

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 8601RFC3339格式,比如: 2021-01-01T00:00:00.000Z
updatedAt 字符串 更新此惩罚的时间。时间采用ISO 8601RFC3339格式,比如: 2021-01-01T00:00:00.000Z
removedAt 字符串 移除此惩罚的时间。时间采用ISO 8601RFC3339格式,比如: 2021-01-01T00:00:00.000Z
trustedPartner 字符串 代表开发人员实施此惩罚的可信赖合作伙伴
deploymentId 字符串 此惩罚适用的EOS DeploymentId
待定 布尔值 如果此惩罚当前待定,则为True
已自动化 布尔值 如果此惩罚通过开发人员门户网站中的手动操作以外的方法创建,则为True
元数据 SanctionMetadata 与此惩罚关联的任意元数据键/值对
displayName 字符串 受惩罚用户的显示名称
identityProvider 字符串 受惩罚用户用以验证身份的身份提供商
accountId 字符串 具有指定identityProvider的受惩罚用户的账户ID
status 字符串 惩罚状态。包括活跃、待定、过期、移除

**注意:**时间采用ISO 8601RFC3339格式。例如: 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 8601RFC3339格式。例如: 2021-01-01T00:00:00.000Z
updatedAt 字符串 申诉更新的时间。时间采用ISO 8601RFC3339格式。例如: 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> 分页信息

示例响应