From 971e6dc5c0924b74a30495844a80db389a092c79 Mon Sep 17 00:00:00 2001 From: Syd Xu Date: Fri, 28 Jun 2024 11:19:55 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat(file/rebate):=20=E6=96=B0=E5=A2=9E24?= =?UTF-8?q?=E5=B9=B4=E7=AB=9E=E4=BB=B7=E5=B9=BF=E5=91=8A=E6=98=8E=E7=82=B9?= =?UTF-8?q?=E6=95=B0=E6=8D=AEAPI=EF=BC=8C=E6=94=AF=E6=8C=81=E9=9B=86?= =?UTF-8?q?=E5=9B=A2=E7=BB=B4=E5=BA=A6=E6=95=B0=E6=8D=AE=E6=9F=A5=E8=AF=A2?= =?UTF-8?q?=E3=80=81=E4=BB=BB=E5=8A=A1=E4=B8=8B=E8=BD=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- marketing-api/OCEANENGINE.md | 4 + marketing-api/api/file/rebate/doc.go | 2 + .../rebate/material_download_create_task.go | 16 +++ .../api/file/rebate/material_download_file.go | 18 +++ .../rebate/material_download_task_list.go | 16 +++ marketing-api/enum/material_policy_type.go | 13 +++ marketing-api/enum/rebate_calc_policy_type.go | 13 +++ .../enum/rebate_calc_settlement_stats_type.go | 15 +++ marketing-api/enum/rebate_material_tag.go | 13 +++ marketing-api/enum/rebate_operator_type.go | 13 +++ marketing-api/enum/yesno.go | 8 ++ marketing-api/model/file/rebate/doc.go | 2 + .../rebate/material_download_create_task.go | 105 ++++++++++++++++++ .../file/rebate/material_download_file.go | 33 ++++++ .../rebate/material_download_task_list.go | 72 ++++++++++++ 15 files changed, 343 insertions(+) create mode 100644 marketing-api/api/file/rebate/doc.go create mode 100644 marketing-api/api/file/rebate/material_download_create_task.go create mode 100644 marketing-api/api/file/rebate/material_download_file.go create mode 100644 marketing-api/api/file/rebate/material_download_task_list.go create mode 100644 marketing-api/enum/material_policy_type.go create mode 100644 marketing-api/enum/rebate_calc_policy_type.go create mode 100644 marketing-api/enum/rebate_calc_settlement_stats_type.go create mode 100644 marketing-api/enum/rebate_material_tag.go create mode 100644 marketing-api/enum/rebate_operator_type.go create mode 100644 marketing-api/enum/yesno.go create mode 100644 marketing-api/model/file/rebate/doc.go create mode 100644 marketing-api/model/file/rebate/material_download_create_task.go create mode 100644 marketing-api/model/file/rebate/material_download_file.go create mode 100644 marketing-api/model/file/rebate/material_download_task_list.go diff --git a/marketing-api/OCEANENGINE.md b/marketing-api/OCEANENGINE.md index 865cc9a6..41e1138b 100644 --- a/marketing-api/OCEANENGINE.md +++ b/marketing-api/OCEANENGINE.md @@ -242,6 +242,10 @@ - 批量删除图集 [ CarouselDelete(clt *core.SDKClient, accessToken string, req *file.CarouselDeleteRequest) (*file.CarouselDeleteResult, error) ] - 【代理商】上传自产首发素材至方舟（搬运治理） [ VideoAgent(clt *core.SDKClient, accessToken string, req *file.VideoAgentRequest) (*file.Video, error) ] - 【代理商】明点无效素材查询 [ RebateMaterialSearch(clt *core.SDKClient, accessToken string, req *file.RebateMaterialSearchRequest) (*file.RebateMaterialSearchResult, error) ] + - 【代理】返点明点化素材数据 (api/file/rebate) + - 创建下载任务 [ MaterialDownloadCreateTask(clt *core.SDKClient, accessToken string, req *rebate.MaterialDownloadCreateTaskRequest) (string, error) ] + - 查询下载任务 [ MaterialDownloadTaskList(clt *core.SDKClient, accessToken string, req *rebate.MaterialDownloadTaskListRequest) (*rebate.MaterialDonwloadTaskListResult, error) ] + - 下载任务结果 [ MaterialDownloadFile(clt *core.SDKClient, accessToken string, req *rebate.MaterialDownloadFileRequest) (json.RawMessage, error) ] - 建站管理 - 橙子建站落地页管理 (tools/site) - 创建橙子建站站点 [ Create(clt *core.SDKClient, accessToken string, req *site.CreateRequest) (uint64, error) ] diff --git a/marketing-api/api/file/rebate/doc.go b/marketing-api/api/file/rebate/doc.go new file mode 100644 index 00000000..4e00bf76 --- /dev/null +++ b/marketing-api/api/file/rebate/doc.go @@ -0,0 +1,2 @@ +// Package rebate 【代理】返点明点化素材数据 +package rebate diff --git a/marketing-api/api/file/rebate/material_download_create_task.go b/marketing-api/api/file/rebate/material_download_create_task.go new file mode 100644 index 00000000..d8078506 --- /dev/null +++ b/marketing-api/api/file/rebate/material_download_create_task.go @@ -0,0 +1,16 @@ +package rebate + +import ( + "github.com/bububa/oceanengine/marketing-api/core" + "github.com/bububa/oceanengine/marketing-api/model/file/rebate" +) + +// MaterialDownloadCreateTask 创建下载任务 +// 根据筛选条件创建明点化素材相关指标的下载任务,返回用户query_id,用于后续的文件下载 +func MaterialDownloadCreateTask(clt *core.SDKClient, accessToken string, req *rebate.MaterialDownloadCreateTaskRequest) (string, error) { + var resp rebate.MaterialDownloadCreateTaskResponse + if err := clt.Post("2/file/rebate/material_download/create_task/", req, &resp, accessToken); err != nil { + return "", err + } + return resp.Data.QueryID, nil +} diff --git a/marketing-api/api/file/rebate/material_download_file.go b/marketing-api/api/file/rebate/material_download_file.go new file mode 100644 index 00000000..137b90d0 --- /dev/null +++ b/marketing-api/api/file/rebate/material_download_file.go @@ -0,0 +1,18 @@ +package rebate + +import ( + "encoding/json" + + "github.com/bububa/oceanengine/marketing-api/core" + "github.com/bububa/oceanengine/marketing-api/model/file/rebate" +) + +// MaterialDownloadFile 下载任务结果 +// 通过指定的task_id,获取对应的数据明细文件 +func MaterialDownloadFile(clt *core.SDKClient, accessToken string, req *rebate.MaterialDownloadFileRequest) (json.RawMessage, error) { + var resp rebate.MaterialDownloadFileResponse + if err := clt.Get("2/file/rebate/material_download/download_file/", req, &resp, accessToken); err != nil { + return nil, err + } + return resp.Data, nil +} diff --git a/marketing-api/api/file/rebate/material_download_task_list.go b/marketing-api/api/file/rebate/material_download_task_list.go new file mode 100644 index 00000000..abde1d1c --- /dev/null +++ b/marketing-api/api/file/rebate/material_download_task_list.go @@ -0,0 +1,16 @@ +package rebate + +import ( + "github.com/bububa/oceanengine/marketing-api/core" + "github.com/bububa/oceanengine/marketing-api/model/file/rebate" +) + +// MaterialDownloadTaskList 查询下载任务 +// 查询指定query_id的所有下载任务 +func MaterialDownloadTaskList(clt *core.SDKClient, accessToken string, req *rebate.MaterialDownloadTaskListRequest) (*rebate.MaterialDonwloadTaskListResult, error) { + var resp rebate.MaterialDownloadTaskListResponse + if err := clt.Get("2/file/rebate/material_download/get_download_task_list/", req, &resp, accessToken); err != nil { + return nil, err + } + return resp.Data, nil +} diff --git a/marketing-api/enum/material_policy_type.go b/marketing-api/enum/material_policy_type.go new file mode 100644 index 00000000..4351fc11 --- /dev/null +++ b/marketing-api/enum/material_policy_type.go @@ -0,0 +1,13 @@ +package enum + +// MaterialPolicyType 素材政策类型 +type MaterialPolicyType string + +const ( + // VALID_ORIGINAL_MATERIAL_RATE 有效首投占比 + VALID_ORIGINAL_MATERIAL_RATE MaterialPolicyType = "VALID_ORIGINAL_MATERIAL_RATE" + // VALID_FIRST_EFFECTIVE_MATERIAL 有效首发素材 + VALID_FIRST_EFFECTIVE_MATERIAL MaterialPolicyType = "VALID_FIRST_EFFECTIVE_MATERIAL" + // VALID_HIGH_QUALITY_MATERIAL 有效优质素材 + VALID_HIGH_QUALITY_MATERIAL MaterialPolicyType = "VALID_HIGH_QUALITY_MATERIAL" +) diff --git a/marketing-api/enum/rebate_calc_policy_type.go b/marketing-api/enum/rebate_calc_policy_type.go new file mode 100644 index 00000000..1076c860 --- /dev/null +++ b/marketing-api/enum/rebate_calc_policy_type.go @@ -0,0 +1,13 @@ +package enum + +// RebateCalcPolicyType 政策类型 +type RebateCalcPolicyType string + +const ( + // RebateCalcPolicyType_NORMAL_POLICY 综代政策 + RebateCalcPolicyType_NORMAL_POLICY RebateCalcPolicyType = "NORMAL_POLICY" + // RebateCalcPolicyType_EXCLUSIVE_POLICY 优代政策 + RebateCalcPolicyType_EXCLUSIVE_POLICY RebateCalcPolicyType = "EXCLUSIVE_POLICY" + // RebateCalcPolicyType_CAR_POLICY 汽车政策 + RebateCalcPolicyType_CAR_POLICY RebateCalcPolicyType = "CAR_POLICY" +) diff --git a/marketing-api/enum/rebate_calc_settlement_stats_type.go b/marketing-api/enum/rebate_calc_settlement_stats_type.go new file mode 100644 index 00000000..1cd22b41 --- /dev/null +++ b/marketing-api/enum/rebate_calc_settlement_stats_type.go @@ -0,0 +1,15 @@ +package enum + +// RebateCalcSettlementStatsType 结算行业统计类型 +type RebateCalcSettlementStatsType string + +const ( + // RebateCalcSettlementStatsType_NORMAL_INDUSTRY 行业类目 + RebateCalcSettlementStatsType_NORMAL_INDUSTRY RebateCalcSettlementStatsType = "NORMAL_INDUSTRY" + // RebateCalcSettlementStatsType_E_COMMERCE 引流电商 + RebateCalcSettlementStatsType_E_COMMERCE RebateCalcSettlementStatsType = "E_COMMERCE" + // RebateCalcSettlementStatsType_TASK_INCENTIVES 任务激励 + RebateCalcSettlementStatsType_TASK_INCENTIVES RebateCalcSettlementStatsType = "TASK_INCENTIVES" + // RebateCalcSettlementStatsType_WECHAT_INCREASE 微信加粉 + RebateCalcSettlementStatsType_WECHAT_INCREASE RebateCalcSettlementStatsType = "WECHAT_INCREASE" +) diff --git a/marketing-api/enum/rebate_material_tag.go b/marketing-api/enum/rebate_material_tag.go new file mode 100644 index 00000000..ae89aebd --- /dev/null +++ b/marketing-api/enum/rebate_material_tag.go @@ -0,0 +1,13 @@ +package enum + +// RebateMaterialTag 素材标签筛选项 +type RebateMaterialTag string + +const ( + // RebateMaterialTag_HIGH_QUALITY_MATERIAL（优质素材） + RebateMaterialTag_HIGH_QUALITY_MATERIAL RebateMaterialTag = "HIGH_QUALITY_MATERIAL" + // RebateMaterialTag_LOW_QUALITY_MATERIAL（低质素材） + RebateMaterialTag_LOW_QUALITY_MATERIAL RebateMaterialTag = "LOW_QUALITY_MATERIAL" + // RebateMaterialTag_FIRST_EFFECTIVE_MATERIAL（首发素材） + RebateMaterialTag_FIRST_EFFECTIVE_MATERIAL RebateMaterialTag = "FIRST_EFFECTIVE_MATERIAL" +) diff --git a/marketing-api/enum/rebate_operator_type.go b/marketing-api/enum/rebate_operator_type.go new file mode 100644 index 00000000..86138a6a --- /dev/null +++ b/marketing-api/enum/rebate_operator_type.go @@ -0,0 +1,13 @@ +package enum + +// RebateOperatorTag 运营标签 +type RebateOperatorTag string + +const ( + // RebateOperatorTag_SHOULIANG 收量 + RebateOperatorTag_SHOULIANG RebateOperatorTag = "SHOULIANG" + // RebateOperatorTag_ZOULIANG 走量 + RebateOperatorTag_ZOULIANG RebateOperatorTag = "ZOULIANG" + // RebateOperatorTag_ZIYUNYING 自运营 + RebateOperatorTag_ZIYUNYING RebateOperatorTag = "ZIYUNYING" +) diff --git a/marketing-api/enum/yesno.go b/marketing-api/enum/yesno.go new file mode 100644 index 00000000..33f8ca38 --- /dev/null +++ b/marketing-api/enum/yesno.go @@ -0,0 +1,8 @@ +package enum + +type YesNo string + +const ( + Yes YesNo = "YES" + No YesNo = "NO" +) diff --git a/marketing-api/model/file/rebate/doc.go b/marketing-api/model/file/rebate/doc.go new file mode 100644 index 00000000..4e00bf76 --- /dev/null +++ b/marketing-api/model/file/rebate/doc.go @@ -0,0 +1,2 @@ +// Package rebate 【代理】返点明点化素材数据 +package rebate diff --git a/marketing-api/model/file/rebate/material_download_create_task.go b/marketing-api/model/file/rebate/material_download_create_task.go new file mode 100644 index 00000000..18adf79a --- /dev/null +++ b/marketing-api/model/file/rebate/material_download_create_task.go @@ -0,0 +1,105 @@ +package rebate + +import ( + "github.com/bububa/oceanengine/marketing-api/enum" + "github.com/bububa/oceanengine/marketing-api/model" + "github.com/bububa/oceanengine/marketing-api/util" +) + +// MaterialDownloadCreateTaskRequest 创建下载任务 API Request +type MaterialDownloadCreateTaskRequest struct { + // AgentID 代理商帐户Id + AgentID uint64 `json:"agent_id,omitempty"` + // Period 业绩消耗年月 年月 格式：yyyy-MM + // 默认值：当前月份（如2024-04 ） + // 最早允许传入时间：2024-04 + Period string `json:"period,omitempty"` + // MaterialPolicyType 素材政策类型 可选值: + // VALID_ORIGINAL_MATERIAL_RATE 有效首投占比 + // VALID_FIRST_EFFECTIVE_MATERIAL 有效首发素材 + // VALID_HIGH_QUALITY_MATERIAL 有效优质素材 + MaterialPolicyType enum.MaterialPolicyType `json:"material_policy_type,omitempty"` + // Filtering 过滤条件 + Filtering *MaterialDownloadCreateTaskFilter `json:"filtering,omitempty"` +} + +// MaterialDownloadCreateTaskFilter +type MaterialDownloadCreateTaskFilter struct { + // FirstEffectivePeroid 素材首投所在月 格式：yyyy-MM + // 默认值：当前月份（如2024-04 ） + // 最早允许传入时间：2024-04 + FirstEffectivePeroid string `json:"first_effective_period,omitempty"` + // AdvertiserID 广告主id + AdvertiserID uint64 `json:"advertiser_id,omitempty"` + // CustomerName 客户名称 + // 如果名称涉及括号，使用英文括号 + CustomerName string `json:"customer_name,omitempty"` + // OperatorTag 运营标签 可选值: + // SHOULIANG 收量 + // ZOULIANG 走量 + // ZIYUNYING 自运营 + OperatorTag enum.RebateOperatorTag `json:"operator_tag,omitempty"` + // RebateCalcPolicyType 政策类型 可选值: + // NORMAL_POLICY 综代政策 + // EXCLUSIVE_POLICY 优代政策 + // CAR_POLICY 汽车政策 + RebateCalcPolicyType enum.RebateCalcPolicyType `json:"rebate_calc_policy_type,omitempty"` + // RebateCalcSettlementStatsType 结算行业统计类型 可选值: + // NORMAL_INDUSTRY 行业类目 + // E_COMMERCE 引流电商 + // TASK_INCENTIVES 任务激励 + // WECHAT_INCREASE微信加粉 + RebateCalcSettlementStatsType enum.RebateCalcSettlementStatsType `json:"rebate_calc_settlement_stats_type,omitempty"` + // RebateCalcFirstIndustryName 一级结算行业 + RebateCalcFirstIndustryName string `json:"rebate_calc_first_industry_name,omitempty"` + // RebateCalcSecondIndustryName 二级结算行业 + RebateCalcSecondIndustryName string `json:"rebate_calc_second_industry_name,omitempty"` + // MaterialTag 素材标签筛选项（如传入多个标签，取交集） + // HIGH_QUALITY_MATERIAL（优质素材） + // LOW_QUALITY_MATERIAL（低质素材） + // FIRST_EFFECTIVE_MATERIAL（首发素材） + MaterialTag []enum.RebateMaterialTag `json:"material_tag,omitempty"` + // IsLiveRebateType 是否直播返点类型（仅支持有效优质或有效首发查询时筛选，入参有效首投，该筛选需要置空） 可选值: + // NO 否 + // YES 是 + IsLiveRebateType enum.YesNo `json:"is_live_rebate_type,omitempty"` + // IsAccumulation 是否累量 可选值: + // NO 否 + // YES 是 + IsAccumulation enum.YesNo `json:"is_accumulation,omitempty"` + // IsValidMaterial 【政策粒度】是否有效素材 可选值: + // NO 否 + // YES 是 + IsValidMaterial enum.YesNo `json:"is_valid_material,omitempty"` + // PolicyCostMin 【政策粒度】累量消耗范围区间下限 + // - 仅支持录入整数,单位：元 + PolicyCostMin int64 `json:"policy_cost_min,omitempty"` + // PolicyCostMax 【政策粒度】累量消耗范围区间上限 + PolicyCostMax int64 `json:"policy_cost_max,omitempty"` + // MaterialIsEffective 数据更新日期前一日是否在投 可选值: + // NO 否 + // YES 是 + MaterialIsEffective enum.YesNo `json:"material_is_effective,omitempty"` + // MaterialFirstEffectiveStartDate 素材首投日期范围开始日期 + // 格式：yyyy-MM-dd + MaterialFirstEffectiveStartDate string `json:"material_first_effective_start_date,omitempty"` + // MaterialFirstEffectiveEndDate 素材首投日期范围结束日期 + // 格式：yyyy-MM-dd + MaterialFirstEffectiveEndDate string `json:"material_first_effective_end_date,omitempty"` + // ThisPeriodCumDayNum 本期已累量天数 + ThisPeriodCumDayNum int `json:"this_period_cum_day_num,omitempty"` +} + +// Encode implements PostRequest interface +func (r MaterialDownloadCreateTaskRequest) Encode() []byte { + return util.JSONMarshal(r) +} + +// MaterialDownloadCreateTaskResponse 创建下载任务 API Response +type MaterialDownloadCreateTaskResponse struct { + model.BaseResponse + Data struct { + // QueryID 下载任务对应的查询ID + QueryID string `json:"query_id,omitempty"` + } `json:"data,omitempty"` +} diff --git a/marketing-api/model/file/rebate/material_download_file.go b/marketing-api/model/file/rebate/material_download_file.go new file mode 100644 index 00000000..551a551f --- /dev/null +++ b/marketing-api/model/file/rebate/material_download_file.go @@ -0,0 +1,33 @@ +package rebate + +import ( + "encoding/json" + "strconv" + + "github.com/bububa/oceanengine/marketing-api/model" + "github.com/bububa/oceanengine/marketing-api/util" +) + +// MaterialDownloadFileRequest 下载任务结果 +type MaterialDownloadFileRequest struct { + // AgentID 代理商帐户ID + AgentID uint64 `json:"agent_id,omitempty"` + // TaskID 任务ID + TaskID string `json:"task_id,omitempty"` +} + +// Encode implements GetRequest interface +func (r MaterialDownloadFileRequest) Encode() string { + values := util.GetUrlValues() + values.Set("agent_id", strconv.FormatUint(r.AgentID, 10)) + values.Set("task_id", r.TaskID) + ret := values.Encode() + util.PutUrlValues(values) + return ret +} + +// MaterialDownloadFileResponse 下载任务结果 +type MaterialDownloadFileResponse struct { + model.BaseResponse + Data json.RawMessage `json:"data,omitempty"` +} diff --git a/marketing-api/model/file/rebate/material_download_task_list.go b/marketing-api/model/file/rebate/material_download_task_list.go new file mode 100644 index 00000000..f8e36579 --- /dev/null +++ b/marketing-api/model/file/rebate/material_download_task_list.go @@ -0,0 +1,72 @@ +package rebate + +import ( + "strconv" + + "github.com/bububa/oceanengine/marketing-api/model" + "github.com/bububa/oceanengine/marketing-api/util" +) + +// QueryStatus 查询状态 +type QueryStatus int + +const ( + // QueryStatus_INIT 初始化 + QueryStatus_INIT QueryStatus = 1 + // QueryStatus_PROCESSING 运行中 + QueryStatus_PROCESSING QueryStatus = 2 + // QueryStatus_SUCCEED 成功 + QueryStatus_SUCCEED QueryStatus = 3 + // QueryStatus_FAILED 失败 + QueryStatus_FAILED QueryStatus = 4 +) + +// MaterialDownloadTaskListRequest 查询下载任务 API Request +type MaterialDownloadTaskListRequest struct { + // AgentID 代理商帐户ID + AgentID uint64 `json:"agent_id,omitempty"` + // QueryID 下载任务查询ID（对应创建 下载任务接口 返回的query_id，建议必填） + QueryID string `json:"query_id,omitempty"` +} + +// Encode implements GetRequest interface +func (r MaterialDownloadTaskListRequest) Encode() string { + values := util.GetUrlValues() + values.Set("agent_id", strconv.FormatUint(r.AgentID, 10)) + if r.QueryID != "" { + values.Set("query_id", r.QueryID) + } + ret := values.Encode() + util.PutUrlValues(values) + return ret +} + +// MaterialDownloadTaskListResponse 查询下载任务 API Response +type MaterialDownloadTaskListResponse struct { + model.BaseResponse + Data *MaterialDonwloadTaskListResult `json:"data,omitempty"` +} + +type MaterialDonwloadTaskListResult struct { + // QueryList 查询ID列表 + QueryList []MaterialDownloadTaskQuery `json:"query_list,omitempty"` + // TaskList 任务ID列表 + TaskList []MaterialDownloadTask `json:"task_list,omitempty"` + // QueryStatus 查询状态 + // 1- 初始化，2-运行中，3-成功，4-失败 + QueryStatus QueryStatus `json:"query_status,omitempty"` +} + +// MaterialDownloadTaskQuery 查询ID +type MaterialDownloadTaskQuery struct { + // QueryID 查询ID + QueryID string `json:"query_id,omitempty"` +} + +// MaterialDownloadTask 任务 +type MaterialDownloadTask struct { + // TaskID 任务ID + TaskID string `json:"task_id,omitempty"` + // CreateTime 任务创建时间 + CreateTime string `json:"create_time,omitempty"` +} From d9cb4cbbb20c9d7d6058ee8d50a3f3f142936f9e Mon Sep 17 00:00:00 2001 From: Syd Xu Date: Fri, 28 Jun 2024 11:47:51 +0800 Subject: [PATCH 2/2] =?UTF-8?q?feat(v3/project):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E6=94=AF=E6=8C=81=E6=9F=A5=E8=AF=A2UBmax?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E6=88=90=E6=9C=AC=E4=BF=9D=E9=9A=9C=E5=8F=8A?= =?UTF-8?q?=E8=B5=94=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"` +}