From d9cb4cbbb20c9d7d6058ee8d50a3f3f142936f9e Mon Sep 17 00:00:00 2001 From: Syd Xu Date: Fri, 28 Jun 2024 11:47:51 +0800 Subject: [PATCH] =?UTF-8?q?feat(v3/project):=20=E6=96=B0=E5=A2=9E=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E6=94=AF=E6=8C=81=E6=9F=A5=E8=AF=A2UBmax=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=88=90=E6=9C=AC=E4=BF=9D=E9=9A=9C=E5=8F=8A=E8=B5=94?= =?UTF-8?q?=E4=BB=98=E4=BF=A1=E6=81=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- marketing-api/OCEANENGINE.md | 1 + .../api/v3/project/cost_protect_status_get.go | 16 ++++ marketing-api/enum/compensate_end_reason.go | 15 ++++ .../enum/compensate_invalid_reason.go | 25 ++++++ marketing-api/enum/compensate_status.go | 23 ++++++ .../v3/project/cost_protect_status_get.go | 79 +++++++++++++++++++ 6 files changed, 159 insertions(+) create mode 100644 marketing-api/api/v3/project/cost_protect_status_get.go create mode 100644 marketing-api/enum/compensate_end_reason.go create mode 100644 marketing-api/enum/compensate_invalid_reason.go create mode 100644 marketing-api/enum/compensate_status.go create mode 100644 marketing-api/model/v3/project/cost_protect_status_get.go diff --git a/marketing-api/OCEANENGINE.md b/marketing-api/OCEANENGINE.md index 41e1138b..f001c9e3 100644 --- a/marketing-api/OCEANENGINE.md +++ b/marketing-api/OCEANENGINE.md @@ -95,6 +95,7 @@ - 获取项目列表 [ List(clt *core.SDKClient, accessToken string, req *project.ListRequest) (*project.ListResponseData, error) ] - 批量更新项目状态 [ StatusUpdate(clt *core.SDKClient, accessToken string, req *project.StatusUpdateRequest) (*project.UpdateResponseData, error) ] - 批量删除项目 [ Delete(clt *core.SDKClient, accessToken string, req *project.DeleteRequest) (*project.UpdateResponseData, error) ] + - 批量获取项目成本保障状态 [ CostProtectStatusGet(clt *core.SDKClient, accessToken string, req *project.CostProtectStatusGetRequest) (*project.CostProtectStatusGetResult, error) ] - 批量更新项目预算 [ BudgetUpdate(clt *core.SDKClient, accessToken string, req *project.BudgetUpdateRequest) (*project.UpdateResponseData, error) ] - 批量更新项目投放时间 [ ScheduleTimeUpdate(clt *core.SDKClient, accessToken string, req *project.ScheduleTimeUpdateRequest) (*project.UpdateResponseData, error) ] - 批量更新项目投放时段 [ WeekScheduleUpdate(clt *core.SDKClient, accessToken string, req *project.WeekScheduleUpdateRequest) (*project.UpdateResponseData, error) ] diff --git a/marketing-api/api/v3/project/cost_protect_status_get.go b/marketing-api/api/v3/project/cost_protect_status_get.go new file mode 100644 index 00000000..9cf6ef3d --- /dev/null +++ b/marketing-api/api/v3/project/cost_protect_status_get.go @@ -0,0 +1,16 @@ +package project + +import ( + "github.com/bububa/oceanengine/marketing-api/core" + "github.com/bububa/oceanengine/marketing-api/model/v3/project" +) + +// CostProtectStatusGet 批量获取项目成本保障状态 +// 本接口支持批量查询项目的成本保障状态及相关赔付信息（接口能力仅对齐巨量广告升级版），对应平台能力如下图所示 +func CostProtectStatusGet(clt *core.SDKClient, accessToken string, req *project.CostProtectStatusGetRequest) (*project.CostProtectStatusGetResult, error) { + var resp project.CostProtectStatusGetResponse + if err := clt.Get("v3.0/project/cost_protect_status/get/", req, &resp, accessToken); err != nil { + return nil, err + } + return resp.Data, nil +} diff --git a/marketing-api/enum/compensate_end_reason.go b/marketing-api/enum/compensate_end_reason.go new file mode 100644 index 00000000..76dcc3dc --- /dev/null +++ b/marketing-api/enum/compensate_end_reason.go @@ -0,0 +1,15 @@ +package enum + +// CompensateEndReason 成本保障结束原因 +type CompensateEndReason string + +const ( + // CompensateEndReason_UN_OBERCOST 超成本比例没有达到1.2倍 + CompensateEndReason_UN_OBERCOST CompensateEndReason = "UN_OBERCOST" + // CompensateEndReason_ROI_REAL_EXPECTED实际roi大于目标roi的80% + CompensateEndReason_ROI_REAL_EXPECTED CompensateEndReason = "ROI_REAL_EXPECTED" + // CompensateEndReason_CONVERT_UNDER_THRESHOLD转化数没有达到门槛 + CompensateEndReason_CONVERT_UNDER_THRESHOLD CompensateEndReason = "CONVERT_UNDER_THRESHOLD" + // CompensateEndReason_CURRENCY_PRECISION赔付金额小于0.01元 + CompensateEndReason_CURRENCY_PRECISION CompensateEndReason = "CURRENCY_PRECISION" +) diff --git a/marketing-api/enum/compensate_invalid_reason.go b/marketing-api/enum/compensate_invalid_reason.go new file mode 100644 index 00000000..9798a83b --- /dev/null +++ b/marketing-api/enum/compensate_invalid_reason.go @@ -0,0 +1,25 @@ +package enum + +// CompensateInvalidReason 成本保障失效原因 +type CompensateInvalidReason string + +const ( + // CompensateInvalidReason_AUD_CHANGES 单日修改定向超过2次 + CompensateInvalidReason_AUD_CHANGES CompensateInvalidReason = "AUD_CHANGES" + // CompensateInvalidReason_BID_CHANGES 单日修改出价超过2次 + CompensateInvalidReason_BID_CHANGES CompensateInvalidReason = "BID_CHANGES" + // CompensateInvalidReason_ROI_CHANGES 单日修改roi_goal超过2次 + CompensateInvalidReason_ROI_CHANGES CompensateInvalidReason = "ROI_CHANGES" + // CompensateInvalidReason_ANTI_SPAM 命中反作弊 + CompensateInvalidReason_ANTI_SPAM CompensateInvalidReason = "ANTI_SPAM" + // CompensateInvalidReason_BID_TYPE_EXPIRED 选择的出价产品暂不支持成本保障 + CompensateInvalidReason_BID_TYPE_EXPIRED CompensateInvalidReason = "BID_TYPE_EXPIRED" + // CompensateInvalidReason_MANUAL_JUDGE_SPAM 有异常的作弊行为 + CompensateInvalidReason_MANUAL_JUDGE_SPAM CompensateInvalidReason = "MANUAL_JUDGE_SPAM" + // CompensateInvalidReason_AUD_BID_CHANGES 单日修改定向/出价超过2次 + CompensateInvalidReason_AUD_BID_CHANGES CompensateInvalidReason = "AUD_BID_CHANGES" + // CompensateInvalidReason_AUD_ROI_CHANGES 单日修改定向/ROI目标超过2次 + CompensateInvalidReason_AUD_ROI_CHANGES CompensateInvalidReason = "AUD_ROI_CHANGES" + // CompensateInvalidReason_ACCOUNT_TRANSFER_APPLICATION 申请转户 + CompensateInvalidReason_ACCOUNT_TRANSFER_APPLICATION CompensateInvalidReason = "ACCOUNT_TRANSFER_APPLICATION" +) diff --git a/marketing-api/enum/compensate_status.go b/marketing-api/enum/compensate_status.go new file mode 100644 index 00000000..6a56358c --- /dev/null +++ b/marketing-api/enum/compensate_status.go @@ -0,0 +1,23 @@ +package enum + +// CompensateStatus 计划成本保障状态 +type CompensateStatus string + +const ( + // CompensateStatus_IN_EFFECT 成本保障生效中 + CompensateStatus_IN_EFFECT CompensateStatus = "IN_EFFECT" + // CompensateStatus_INVALID 成本保障已失效 + CompensateStatus_INVALID CompensateStatus = "INVALID" + // CompensateStatus_CONFIRMING 成本保障确认中 + CompensateStatus_CONFIRMING CompensateStatus = "CONFIRMING" + // CompensateStatus_PAID 成本保障已到账 + CompensateStatus_PAID CompensateStatus = "PAID" + // CompensateStatus_ENDED 成本保障已结束 + CompensateStatus_ENDED CompensateStatus = "ENDED" + // CompensateStatus_DEFAULT 无成本保障状态 + CompensateStatus_DEFAULT CompensateStatus = "DEFAULT" + // CompensateStatus_FAILED 成本保障查询超时，请重试 + CompensateStatus_FAILED CompensateStatus = "FAILED" + // CompensateStatus_UNSUPPORTED 查询失败，传入参数project信息有误，多为project_id在账户下不存在 + CompensateStatus_UNSUPPORTED CompensateStatus = "UNSUPPORTED" +) diff --git a/marketing-api/model/v3/project/cost_protect_status_get.go b/marketing-api/model/v3/project/cost_protect_status_get.go new file mode 100644 index 00000000..41d7221b --- /dev/null +++ b/marketing-api/model/v3/project/cost_protect_status_get.go @@ -0,0 +1,79 @@ +package project + +import ( + "strconv" + + "github.com/bububa/oceanengine/marketing-api/enum" + "github.com/bububa/oceanengine/marketing-api/model" + "github.com/bububa/oceanengine/marketing-api/util" +) + +// CostProtectStatusGetRequest 批量获取项目成本保障状态 API Request +type CostProtectStatusGetRequest struct { + // AdvertiserID 巨量广告平台广告主id + AdvertiserID uint64 `json:"advertiser_id,omitempty"` + // ProjectIDs 项目id列表，每次最多传入50个 + // 注意：仅允许传入广告账户下存在的project_id，否则应答参数中compensate_status会返回UNSUPPORTED表示查询失败，因为该项目在advertiser_id下不存在 + ProjectIDs []uint64 `json:"project_ids,omitempty"` +} + +// Encode implements GetRequest interface +func (r CostProtectStatusGetRequest) Encode() string { + values := util.GetUrlValues() + values.Set("advertiser_id", strconv.FormatUint(r.AdvertiserID, 10)) + values.Set("project_ids", string(util.JSONMarshal(r.ProjectIDs))) + ret := values.Encode() + util.PutUrlValues(values) + return ret +} + +// CostProtectStatusGetResponse 批量获取项目成本保障状态 API Response +type CostProtectStatusGetResponse struct { + model.BaseResponse + // Data json返回值 + Data *CostProtectStatusGetResult `json:"data,omitempty"` +} + +type CostProtectStatusGetResult struct { + // CompensationStatusInfoList 项目成本保障信息列表 + CompensationStatusInfoList []CompensationStatusInfo `json:"compensation_status_info_list,omitempty"` +} + +// CompensationStatusInfo 项目成本保障信息 +type CompensationStatusInfo struct { + // ProjectID 项目id + ProjectID uint64 `json:"project_id,omitempty"` + // CompensateStatus 项目成本保障状态 可选值: + // CONFIRMING 成本保障确认中 + // ENDED 成本保障已结束 + // INVALID 成本保障已失效 + // IN_EFFECT 成本保障生效中 + // PAID 成本保障已到账 + // DEFAULT 无成本保障状态，表示该项目不支持成本保障，此时在巨量广告升级版平台页面上也不会展示相关标志 + // 其他异常情况返回： + // FAILED 成本保障查询超时，请重试 + // UNSUPPORTED 查询失败，传入参数project信息有误，多为project_id在账户下不存在 + CompensateStatus enum.CompensateStatus `json:"compensate_status,omitempty"` + // CompensateInvalidReasons 成本保障失效原因，仅当compensate_status = INVALID 时&&仅在以下情况会返回。原因可能有多个，因此可能会返回多个枚举 + // AUD_CHANGES单日修改定向超过2次, + // BID_CHANGES单日修改出价超过2次 + // ROI_CHANGES单日修改roi_goal超过2次 + // ANTI_SPAM命中反作弊 + // BID_TYPE_EXPIRED选择的出价产品暂不支持成本保障 + // MANUAL_JUDGE_SPAM有异常的作弊行为 + // AUD_BID_CHANGES单日修改定向/出价超过2次 + // AUD_ROI_CHANGES单日修改定向/ROI目标超过2次 + // ACCOUNT_TRANSFER_APPLICATION 申请转户 + CompensateInvalidReasons []enum.CompensateInvalidReason `json:"compensate_invalid_reasons,omitempty"` + // CompensateEndReasons 成本保障结束原因，仅当compensate_status = ENDED 时&&仅在以下情况会返回 + // 原因可能有多个，因此可能会返回多个枚举 + // UN_OBERCOST 超成本比例没有达到1.2倍 + // ROI_REAL_EXPECTED实际roi大于目标roi的80% + // CONVERT_UNDER_THRESHOLD转化数没有达到门槛 + // CURRENCY_PRECISION赔付金额小于0.01元 + CompensateEndReasons []enum.CompensateEndReason `json:"compensate_end_reasons,omitempty"` + // CompensateAmount 赔付金额（元），最多2位小数 + CompensateAmount float64 `json:"compensate_amount,omitempty"` + // CompensateURL 赔付规则链接，主要为飞书文档地址，如：https://bytedance.larkoffice.com/docx/UWifd88wfou3bmxHAq7ciOgPn9e + CompensateURL string `json:"compensate_url,omitempty"` +}