惩罚Web API

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

本页面的内容

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标头

名称

授权(Authorization)

Bearer <EOSAccessToken>

内容类型(Content-Type)

application/json

路径参数(Path Parameters)

名称

类型

说明

是否必填

ProductUserId

字符串

用于查询惩罚的EOS ProductUserId

查询参数(Query Parameters)

名称

类型

说明

是否必填

操作

字符串

可选操作筛选器。支持多个值: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

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负载

名称

类型

说明

元素

Array<SanctionEvent>

惩罚事件清单

SanctionEvent

productUserId

字符串

受惩罚用户的EOS ProductUserId

操作

字符串

与此惩罚关联的操作字符串

理由

字符串

与此惩罚关联的理由字符串

来源

字符串

创建此惩罚的来源,例如"开发人员门户"

eventType

整型

1:惩罚已创建2:惩罚已更新3:惩罚已删除

标签

Array<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

元数据键/值对。最大项目数:25.项目键最大长度:64.项目值最大长度:128。

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负载

名称

类型

说明

元素

Array<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负载

类型

说明

Array<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

名称

类型

说明

是否必填

productUserId

字符串

受惩罚用户的EOS ProductUserId

操作

字符串

与此惩罚关联的操作字符串。格式:[a-zA-Z0-9_-]+。最小长度:1.最大长度:64.

理由

字符串

与此惩罚关联的理由字符串。最小长度:1 最大长度:2048

来源

字符串

创建此惩罚的来源,例如"开发人员门户"。格式:[a-zA-Z0-9_-]+。最小长度:2.最大长度:64.

标签

Array<String>

与此惩罚关联的标签列表。项目不区分大小写且具有唯一性。 项目格式:[a-zA-Z0-9_-]+。项目最大长度:16

待定

布尔值

如果此惩罚当前待定,则为True

元数据

SanctionMetadata

与此惩罚关联的任意元数据键/值对

displayName

字符串

受惩罚用户的显示名称。最大长度:64

identityProvider

字符串

受惩罚用户用以验证身份的身份提供商。最大长度:64

accountId

字符串

具有指定identityProvider的受惩罚用户的账户ID。最大长度:64

期限

整型

惩罚时长(以秒为单位)

响应

HTTP响应200 - OK:成功。

HTTP标头

名称

内容类型

application/json

JSON负载

名称

类型

说明

元素

Array<Sanction>

已创建惩罚列表

惩罚

productUserId

字符串

受惩罚用户的EOS ProductUserId

操作

字符串

与此惩罚关联的操作字符串

理由

字符串

与此惩罚关联的理由字符串

来源

字符串

创建此惩罚的来源,例如"开发人员门户"

标签

Array<String>

与此惩罚关联的标签列表

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

状态

字符串

此惩罚的状态。包括有效、待定、已过期、已删除

注意:时间采用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>" 

响应

HTTP响应200 - OK:成功。

HTTP标头

名称

内容类型

application/json

JSON负载

名称

类型

说明

元素

Array<Sanction>

按createdAt降序排列的惩罚列表。

分页

Object<Paging>

分页信息

示例响应

{
    "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"
        }
    ],
    "paging": {
        "total": 1,
        "offset": 0,
        "limit": 100
    }
}

查询玩家的所有惩罚

策略

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

  • 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。

示例请求

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

响应

HTTP响应200 - OK:成功。

HTTP标头

名称

内容类型

application/json

JSON负载

名称

类型

说明

元素

Array<Sanction>

按createdAt降序排列的惩罚列表。

分页

Object<Paging>

分页信息

示例响应

{
    "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"
        }
    ],
    "paging": {
        "total": 1,
        "offset": 0,
        "limit": 100
    }
}

更新惩罚

策略

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

授权

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

请求

HTTP请求

PATCH /sanctions/v1/{deploymentId}/sanctions

HTTP标头

名称

授权

Bearer <EOSAccessToken>

内容类型

application/json

路径参数

名称

类型

说明

是否必填

deploymentId

字符串

要查询的deploymentId

JSON负载

类型

说明

Array<SanctionPatchPayload>

适用的惩罚更新列表

示例请求

curl --request PATCH "https://api.epicgames.dev/sanctions/v1/deploymentId1/sanctions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <EOSAccessToken>" \
--data-raw '[{
    "referenceId": "7cd6de84-b5be-405a-8fa1-55c11c821a1e",
    "updates" : {
        "tags": ["updated_example_tag_1","updated_example_tag_2"],
        "justification": "updated_example_justification",
        "metadata": {
            "updated_example_metadata_1":"updated_example_metadata_1",
            "updated_example_metadata_2":"updated_example_metadata_2"
        }
    }
}]'

SanctionPatchPayload

名称

类型

说明

是否必填

referenceId

字符串

此惩罚的唯一标识符

更新

UpdatableFields

要更新的字段及其新值。

UpdatableFields

名称

类型

说明

是否必填

标签

Array<String>

与此惩罚关联的标签列表。项目不区分大小写且具有唯一性。 项目格式:[a-zA-Z0-9_-]+。项目最大长度:16

元数据

SanctionMetadata

与此惩罚关联的任意元数据键/值对

理由

字符串

与此惩罚关联的理由字符串。最小长度:1 最大长度:2048

响应

HTTP响应200 - OK:成功。

HTTP标头

名称

内容类型

application/json

JSON负载

名称

类型

说明

元素

Array<Sanction>

已更新惩罚列表

示例响应

{
    "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": "2022-03-02T20:01:12.311744Z",
            "trustedPartner": null,
            "metadata": {
                "updated_example_metadata_1": "updated_example_metadata_1",
                "updated_example_metadata_2": "updated_example_metadata_2"
            },
            "deploymentId": "deploymentId1",
            "productUserId": "example_product_user_id",
            "pending": false,
            "automated": true,
            "source": "example_source",
            "justification": "updated_example_justification",
            "tags": [
                "updated_example_tag_1",
                "updated_example_tag_2"
            ],
            "action": "EXAMPLE_ACTION",
            "displayName": "example_display_name",
            "identityProvider": "example_identity_provider",
            "accountId": "example_account_id",
            "status": "Active"
        }
    ]
}

取消惩罚

策略

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

授权

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

请求

HTTP请求

DELETE /sanctions/v1/{deploymentId}/sanctions

HTTP标头

名称

授权

Bearer <EOSAccessToken>

内容类型

application/json

路径参数

名称

类型

说明

是否必填

deploymentId

字符串

要查询的deploymentId

JSON负载

类型

说明

SanctionDeletePayload

要删除的惩罚及理由

请求示例

curl --request DELETE "https://api.epicgames.dev/sanctions/v1/{deploymentId}/sanctions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <EOSAccessToken>" \
--data-raw '{
    "referenceIds": ["7cd6de84-b5be-405a-8fa1-55c11c821a1e"],
    "justification" : "example_delete_justification"`
}

SanctionDeletePayload

名称

类型

说明

是否必填

referenceIds

Array<String>

要取消惩罚的唯一标识符

理由

字符串

与取消此惩罚关联的理由字符串。最小长度:1 最大长度:2048

响应

HTTP响应204 - OK:成功。

HTTP标头

名称

内容类型

application/json

JSON负载

名称

类型

说明

元素

Array<Sanction>

已取消惩罚列表

分页

偏移

整型

分页偏移

限制

整型

每次调用返回的惩罚计数

总计

整型

惩罚总数