Merge branch 'release/v1.25.5'

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) ]
@@ -242,6 +243,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) ]

marketing-api/api/file/rebate/doc.go

@@ -0,0 +1,2 @@
+// Package rebate 【代理】返点明点化素材数据
+package rebate

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
+}

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
+}

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
+}

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
+}

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"
+)

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"
+)

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"
+)

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"
+)

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"
+)

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"
+)

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"
+)

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"
+)

marketing-api/enum/yesno.go

@@ -0,0 +1,8 @@
+package enum
+
+type YesNo string
+
+const (
+	Yes YesNo = "YES"
+	No  YesNo = "NO"
+)

marketing-api/model/file/rebate/doc.go

@@ -0,0 +1,2 @@
+// Package rebate 【代理】返点明点化素材数据
+package rebate

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"`
+}

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"`
+}