From 553d64ce420953b28697abedfc1fc5ba56a3996c Mon Sep 17 00:00:00 2001 From: Syd Xu Date: Thu, 10 Oct 2024 13:48:00 +0800 Subject: [PATCH] =?UTF-8?q?feat(file):=20=E5=B7=A8=E9=87=8F=E5=B9=BF?= =?UTF-8?q?=E5=91=8A=E5=B7=B2=E6=94=AF=E6=8C=81=E6=8A=95=E6=94=BE=E6=8A=96?= =?UTF-8?q?=E9=9F=B3=E5=9B=BE=E6=96=87=E7=B4=A0=E6=9D=90=EF=BC=8C=E6=B6=89?= =?UTF-8?q?=E5=8F=8A=E5=B7=A5=E5=85=B7=E3=80=81=E5=B9=BF=E5=91=8A=E7=AE=A1?= =?UTF-8?q?=E7=90=86=E3=80=81=E7=B4=A0=E6=9D=90=E7=AE=A1=E7=90=86=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E6=8E=A5=E5=8F=A3=E6=94=B9=E5=8A=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- marketing-api/OCEANENGINE.md | 1 + marketing-api/api/file/carousel_aweme_get.go | 20 +++++++ marketing-api/model/file/carousel.go | 21 +++++++ .../model/file/carousel_aweme_get.go | 60 +++++++++++++++++++ marketing-api/model/file/carousel_list.go | 8 +++ marketing-api/model/page_info.go | 8 +++ marketing-api/model/tools/aweme_auth_list.go | 13 ++-- marketing-api/model/v3/promotion/promotion.go | 12 ++++ 8 files changed, 138 insertions(+), 5 deletions(-) create mode 100644 marketing-api/api/file/carousel_aweme_get.go create mode 100644 marketing-api/model/file/carousel_aweme_get.go diff --git a/marketing-api/OCEANENGINE.md b/marketing-api/OCEANENGINE.md index bec185db..e23b5def 100644 --- a/marketing-api/OCEANENGINE.md +++ b/marketing-api/OCEANENGINE.md @@ -371,6 +371,7 @@ - 查询推广卡片推荐内容（新版） [ PromotionCardRecommendTitleGet(clt *core.SDKClient, accessToken string, req *tools.PromotionCardRecommendTitleGetRequest) ([]string, error) ] - 获取预估点击成本 [ tools.EstimatedPriceGet(clt *core.SDKClient, accessToken string, req *tools.EstimatedPriceGetRequest) (*tools.EstimatedPrice, error) ] - 获取抖音授权关系 [ tools.AwemeAuthList(clt *core.SDKClient, accessToken string, req *tools.AwemeAuthListRequest) (*tools.AwemeAuthListData, error) ] + - 获取创编可用的抖音图文素材 [ tools.CarouselAwemeGet(ctx context.Context, clt *core.SDKClient, accessToken string, req *file.CarouselAwemeGetRequest) (*file.CarouselAwemeGetResult, error) ] - 查询视频是否挂载下载类锚点 [ tools.CheckAvailableAnchor(clt *core.SDKClient, accessToken string, req *video.CheckAvailableAnchorRequest) ([]video.AvailableAnchor, error) ] - 获取快投推荐出价系数 [ tools.SearchBidRatioGet(clt *core.SDKClient, accessToken string, req *tools.SearchBidRatioGetRequest) (float64, error) ] - 查询白名单能力 [ GrayGet(clt *core.SDKClient, accessToken string, req *tools.GrayGetRequest) ([]tools.GrayItem, error) ] diff --git a/marketing-api/api/file/carousel_aweme_get.go b/marketing-api/api/file/carousel_aweme_get.go new file mode 100644 index 00000000..c88c9555 --- /dev/null +++ b/marketing-api/api/file/carousel_aweme_get.go @@ -0,0 +1,20 @@ +package file + +import ( + "context" + + "github.com/bububa/oceanengine/marketing-api/core" + "github.com/bububa/oceanengine/marketing-api/model/file" +) + +// CarouselAwemeGet 获取创编可用的抖音图文素材 +// 该接口用于获取「巨量广告平台」创建广告时可用的抖音图文素材，您可以获取抖音图文素材的item_id，在广告创编接口使用。 +// 您必须先和抖音号建立以下任意3种生效中的授权关系：抖音号授权、主页作品授权、单个作品授权，才可获取抖音图文素材 +// 当抖音号下没有图文素材时，列表会返回为空 +func CarouselAwemeGet(ctx context.Context, clt *core.SDKClient, accessToken string, req *file.CarouselAwemeGetRequest) (*file.CarouselAwemeGetResult, error) { + var resp file.CarouselAwemeGetResponse + if err := clt.GetAPI(ctx, "v3.0/file/carousel/aweme/get", req, &resp, accessToken); err != nil { + return nil, err + } + return resp.Data, nil +} diff --git a/marketing-api/model/file/carousel.go b/marketing-api/model/file/carousel.go index 180219dc..035bf961 100644 --- a/marketing-api/model/file/carousel.go +++ b/marketing-api/model/file/carousel.go @@ -26,6 +26,8 @@ type Carousel struct { CreateTime string `json:"create_time,omitempty"` // UpdateTime 图集更新时间 UpdateTime string `json:"update_time,omitempty"` + // Source 图文素材来源 + Source string `json:"source,omitempty"` } func (c *Carousel) UnmarshalJSON(data []byte) error { @@ -41,10 +43,29 @@ func (c *Carousel) UnmarshalJSON(data []byte) error { return nil } +// AwemeCarousel 抖音图文素材 +type AwemeCarousel struct { + // ItemID 抖音图文id，在抖音号内上传图文素材时生成的id，是抖音端图文素材的唯一id + ItemID uint64 `json:"item_id,omitempty"` + // MaterialID 抖音图文素材id，在查询素材维度的报表（会用该id作为维度，对应「素材管理」-「获取图文素材」等相关接口中的carousel_ids.id或carousel_id） + MaterialID uint64 `json:"material_id,omitempty"` + // CarouselTitle 抖音图文标题 + CarouselTitle string `json:"carousel_title,omitempty"` + // CarouselPlayURL 抖音图文播放地址，格式为：https://douyin.com/video/XXXXXX + CarouselPlayURL string `json:"carousel_play_url,omitempty"` + // CarouselCoverURL 抖音图文素材内封面图片预览url，有效期10小时 + CarouselCoverURL string `json:"carousel_cover_url,omitempty"` + // Images 抖音图文素材内的图片信息，最多35张图片 + // 按照图文本身的顺序返回，最前面的图片在最上面 + Images []CarouselImage `json:"images,omitempty"` +} + // CarouselImage 图集图片信息，包含图片id和图片主题 type CarouselImage struct { // ImageID 图片id，根据上传广告图片接口获取 ImageID string `json:"image_id,omitempty"` + // MaterialID 素材id + MaterialID uint64 `json:"material_id,omitempty"` // Ratio 图片比例 Ratio float64 `json:"ratio,omitempty"` // Size 图片大小 diff --git a/marketing-api/model/file/carousel_aweme_get.go b/marketing-api/model/file/carousel_aweme_get.go new file mode 100644 index 00000000..79d2d769 --- /dev/null +++ b/marketing-api/model/file/carousel_aweme_get.go @@ -0,0 +1,60 @@ +package file + +import ( + "strconv" + + "github.com/bububa/oceanengine/marketing-api/model" + "github.com/bububa/oceanengine/marketing-api/util" +) + +// CarouselAwemeGetRequest 获取创编可用的抖音图文素材 API Request +type CarouselAwemeGetRequest struct { + // AdvertiserID 巨量广告广告主账户ID + AdvertiserID uint64 `json:"advertiser_id,omitempty"` + // AwemeID 抖音号id + AwemeID string `json:"aweme_id,omitempty"` + // Filtering 过滤器 + Filtering *CarouselAwemeGetFilter `json:"filtering,omitempty"` + // Cursor 页码游标值，第一次拉取，请传入0 + // 不传入或者传空字符串默认使用 + Cursor string `json:"cursor,omitempty"` + // Count 页面数据量，默认10，最大值100 + Count int `json:"count,omitempty"` +} + +type CarouselAwemeGetFilter struct { + // ItemIDs 抖音图文唯一ID + ItemIDs []uint64 `json:"item_ids,omitempty"` +} + +// Encode implements GetRequest interface +func (r CarouselAwemeGetRequest) Encode() string { + values := util.GetUrlValues() + values.Set("advertiser_id", strconv.FormatUint(r.AdvertiserID, 10)) + values.Set("aweme_id", r.AwemeID) + if r.Filtering != nil { + values.Set("filtering", string(util.JSONMarshal(r.Filtering))) + } + if r.Cursor != "" { + values.Set("cursor", r.Cursor) + } + if r.Count > 0 { + values.Set("count", strconv.Itoa(r.Count)) + } + ret := values.Encode() + util.PutUrlValues(values) + return ret +} + +// CarouselAwemeGetResponse 获取创编可用的抖音图文素材 API Response +type CarouselAwemeGetResponse struct { + model.BaseResponse + Data *CarouselAwemeGetResult `json:"data,omitempty"` +} + +type CarouselAwemeGetResult struct { + // CursorInfo 分页信息 + CursorInfo *model.CursorInfo `json:"cursor_info,omitempty"` + // AwemeCarouseList 抖音图文素材列表 + AwemeCarouseList []AwemeCarousel `json:"aweme_carouse_list,omitempty"` +} diff --git a/marketing-api/model/file/carousel_list.go b/marketing-api/model/file/carousel_list.go index 12c6481e..db566514 100644 --- a/marketing-api/model/file/carousel_list.go +++ b/marketing-api/model/file/carousel_list.go @@ -40,6 +40,14 @@ type CarouselListFilter struct { // EndTime 根据图集上传时间进行过滤的结束时间，与start_time搭配使用。 // 格式：yyyy-mm-dd EndTime string `json:"end_time,omitempty"` + // Source 图文素材来源，可选值: + // 本地上传：AD_SITE + // 组织共享：BP + // 账户推送：ACCOUNT_PUSH + // 即创：AIC + // MarketingAPI：OPEN_API + // 抖音主页：CEWEBRITY_CAROUSEL + Source string `json:"source,omitempty"` } // Encode implement GetRequest interface diff --git a/marketing-api/model/page_info.go b/marketing-api/model/page_info.go index f72c9172..6ae9c6a6 100644 --- a/marketing-api/model/page_info.go +++ b/marketing-api/model/page_info.go @@ -17,3 +17,11 @@ type PageInfo struct { // Cursor 下一次分页拉取的游标值 Cursor int `json:"cursor,omitempty"` } + +// CursorInfo 分页信息 +type CursorInfo struct { + // Cursor 下一次分页拉取的游标值 + Cursor string `json:"cursor,omitempty"` + // Count + Count int `json:"count,omitempty"` +} diff --git a/marketing-api/model/tools/aweme_auth_list.go b/marketing-api/model/tools/aweme_auth_list.go index b30bcec4..14aae77d 100644 --- a/marketing-api/model/tools/aweme_auth_list.go +++ b/marketing-api/model/tools/aweme_auth_list.go @@ -11,10 +11,10 @@ import ( // AwemeAuthListRequest 获取抖音授权关系 type AwemeAuthListRequest struct { - // AdvertiserID 广告主ID - AdvertiserID uint64 `json:"advertiser_id,omitempty"` // Filtering 筛选条件 Filtering *AwemeAuthListFilter `json:"filtering,omitempty"` + // AdvertiserID 广告主ID + AdvertiserID uint64 `json:"advertiser_id,omitempty"` // Page 页码 Page int `json:"page,omitempty"` // PageSize 页面大小 @@ -62,17 +62,17 @@ func (r AwemeAuthListRequest) Encode() string { // AwemeAuthListResponse 获取抖音授权关系 type AwemeAuthListResponse struct { - model.BaseResponse // Data json返回值 Data *AwemeAuthListData `json:"data,omitempty"` + model.BaseResponse } // AwemeAuthListData . type AwemeAuthListData struct { - // List . - List []AwemeAuthItem `json:"list,omitempty"` // PageInfo . PageInfo *model.PageInfo `json:"page_info,omitempty"` + // List . + List []AwemeAuthItem `json:"list,omitempty"` } type AwemeAuthItem struct { @@ -113,4 +113,7 @@ type AwemeAuthVideo struct { VideoCoverID string `json:"video_cover_id,omitempty"` // VideoCoverURL 视频封面链接 VideoCoverURL string `json:"video_cover_url,omitempty"` + // Mid 视频素材ID + // （仅抖音视频会有此字段，抖音图文素材没有此字段） + Mid string `json:"mid,omitempty"` } diff --git a/marketing-api/model/v3/promotion/promotion.go b/marketing-api/model/v3/promotion/promotion.go index d49a1ab2..3765aa9f 100644 --- a/marketing-api/model/v3/promotion/promotion.go +++ b/marketing-api/model/v3/promotion/promotion.go @@ -125,9 +125,11 @@ func (p Promotion) GetOptStatus() enum.AdOptStatus { } return "" } + func (p Promotion) GetBudget() float64 { return p.Budget } + func (p Promotion) GetCpaBid() float64 { return p.CpaBid } @@ -452,6 +454,9 @@ type BrandInfo struct { type CarouselMaterial struct { // CarouselID 图集id，可通过【获取图集素材】接口获得 CarouselID string `json:"carousel_id,omitempty"` + // ItemID 抖音图文id，需从【获取创编可用的抖音图文素材】接口获取item_id传入 + // 注意：投放抖音图文素材时，只需要传入item_id，不要传入carousel_id（2个同时传入只会使用item_id） + ItemID uint64 `json:"item_id,omitempty"` // ImageID 图片ID列表 ImageID []string `json:"image_id,omitempty"` // AudioID 音频ID @@ -460,6 +465,13 @@ type CarouselMaterial struct { MaterialStatus string `json:"material_status,omitempty"` // CarouselType 图集素材类型 CarouselType enum.ImageMode `json:"carousel_type,omitempty"` + // VideoHpVisibility 图文主页可见性设置（抖音图文不支持此字段） + // ALWAYS_VISIBLE 主页始终可见 + // HIDE_VIDEO_ON_HP 单次展示可见（原主页隐藏） + VideoHpVisibility enum.VideoHpVisibility `json:"video_hp_visibility,omitempty"` + // IsBlueFlowRecommendMaterial 是系统推荐图文，仅有一个枚举：是 true + // 如果不是，不会返回这个字段 + IsBlueFlowRecommendMaterial bool `json:"is_blue_flow_recommend_material,omitempty"` // ImageSubject 图片主题 ImageSubject []file.ImageSubject `json:"image_subject,omitempty"` }