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

示例请求

curl "https://api.epicgames.dev/sanctions/v1/productUser/<ProductUserId>/active" \
-H "accept: application/json" \
-H "Authorization: Bearer <EOSAccessToken>"

响应

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。

示例请求

curl "https://api.epicgames.dev/sanctions/v1/sync" \
-H "accept: application/json" \
-H "Authorization: Bearer <EOSAccessToken>" \
-G \
-d lastLogId=<LastLogId>

响应

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

示例请求

curl "https://api.epicgames.dev/sanctions/v1/deploymentId1/active-sanctions?productUserId=productUserId1&productUserId=productUserId2&action=action1&action=action2" \
-H "accept: application/json" \
-H "Authorization: Bearer <EOSAccessToken>"

响应

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

CompactSanctionWithPuid

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

示例响应

{
"elements": [
{
"productUserId": "productUserId1",
"referenceId": "example_reference_id_1",
"timestamp": "2020-04-15T13:18:25.431762Z",
"action": "action1",
"expirationTimestamp": null
},
{
"productUserId": "productUserId2",
"referenceId": "example_reference_id_2",
"timestamp": "2020-04-15T13:32:44.261711Z",
"action": "action2",
"expirationTimestamp": null
}
]
}

创建惩罚

策略

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

授权

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

请求

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

示例请求

curl --request POST "https://api.epicgames.dev/sanctions/v1/deploymentId1/sanctions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <EOSAccessToken>" \
--data-raw '[
{
"action": "EXAMPLE_ACTION",
"duration": 0,
"justification": "example_justification",
"source": "example_source",
"productUserId": "example_product_user_id",
"pending": false,
"automated": true,
"tags": ["example_tag_1", "example_tag_2"],
"metadata": {
"example_metadata_1":"meta_1",
"example_metadata_2":"meta_2"
},
"displayName": "example_display_name",
"identityProvider": "example_identity_provider",
"accountId": "example_account_id"
}
]

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 字符串 The status of this sanction. Including Active, Pending, Expired, Removed

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

示例响应

{
"elements": [
{
"referenceId": "7cd6de84-b5be-405a-8fa1-55c11c821a1e",
"timestamp": "2022-03-02T19:54:42.402355Z",
"expirationTimestamp": null,
"batchUuid": "645eba40-dd53-4cea-95d3-3e22459bb84d",
"epicAccountName": null,
"epicAccountId": "",
"eosClientId": "example_client_id",
"eosClientRole": "",
"createdAt": "2022-03-02T19:54:42.402243Z",
"updatedAt": null,
"trustedPartner": null,
"metadata": {
"example_metadata_1": "meta_1",
"example_metadata_2": "meta_2"
},
"deploymentId": "deploymentId1",
"productUserId": "example_product_user_id",
"pending": false,
"automated": true,
"source": "example_source",
"justification": "example_justification",
"tags": ["example_tag_1", "example_tag_2"],
"action": "EXAMPLE_ACTION",
"displayName": "example_display_name",
"identityProvider": "example_identity_provider",
"accountId": "example_account_id",
"status": "Active"
}
]
}

查询所有惩罚

策略

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

  • sanctions:findSanctionsForAnyUser
  • sanctions:findAllSanctions
  • sanctions:syncSanctionEvents

授权

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

请求

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

请求示例

curl --request GET "https://api.epicgames.dev/sanctions/v1/deploymentId1/sanctions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <EOSAccessToken>"

响应