Merge branch 'release/v1.28.2'

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) ]

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

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 图片大小

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

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

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

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

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