lingxingapi 1.0.0__py3-none-any.whl

lingxingapi/ads/param.py

@@ -0,0 +1,192 @@
+# -*- coding: utf-8 -*-
+from typing import Optional
+from pydantic import ValidationInfo, Field, field_validator
+from lingxingapi import utils
+from lingxingapi.base.param import Parameter, PageOffestAndLength
+from lingxingapi.fields import NonEmptyStr, CountryCode, NonNegativeInt
+
+
+# 基础数据 ----------------------------------------------------------------------------------------------------------------------
+# . Ads Profiles
+class AdProfiles(PageOffestAndLength):
+    """查询广告账号参数"""
+
+    profile_type: NonEmptyStr = Field(alias="type")
+
+
+# . Ads Entities (Portfolios, Campaigns, etc.)
+class AdEntities(PageOffestAndLength):
+    """查询广告组合参数"""
+
+    # 领星店铺ID
+    sid: Optional[NonNegativeInt] = None
+    # 亚马逊店铺ID [广告帐号ID] (AdsProfiles.profile_id)
+    profile_id: NonNegativeInt
+    # 广告组合状态 ("enabled", "paused", "archived" | 默认所有)
+    state: Optional[NonEmptyStr] = None
+    # 分页游标, 上次分页结果中的next_token
+    next_token: Optional[NonEmptyStr] = None
+
+
+# . SP Negative Targets
+class SpNegativeTargeting(AdEntities):
+    """查询 SP 否定投放参数"""
+
+    # 否定投放类型 ("keyword", "target")
+    targeting_type: NonEmptyStr = Field(alias="target_type")
+    # 广告活动ID
+    campaign_id: Optional[NonNegativeInt] = None
+
+
+# . SB Targets
+class SbTargeting(AdEntities):
+    """查询 SP 广告投放目标参数"""
+
+    # SB广告类型 ('SB', 'SBV', 'ALL')
+    ad_type: NonEmptyStr = Field(alias="ads_type")
+    # 投放目标类型 ('keyword', 'product', 'ALL')
+    targeting_type: NonEmptyStr
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("targeting_type", mode="before")
+    @classmethod
+    def _validate_targeting_type(cls, v: str) -> str:
+        return "producttarget" if v == "product" else v
+
+
+# 报告 -------------------------------------------------------------------------------------------------------------------------
+# . Ad Reports
+class AdReports(AdEntities):
+    """查询广告报告参数"""
+
+    # 报告日期
+    report_date: str
+    # 是否展示完整归因期信息 (0: 否, 1: 是 | 默认: 0)
+    show_detail: Optional[NonNegativeInt] = None
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("report_date", mode="before")
+    @classmethod
+    def _validate_report_date(cls, v: str) -> str:
+        dt = utils.validate_datetime(v, False, "广告报告日期")
+        return "%04d-%02d-%02d" % (dt.year, dt.month, dt.day)
+
+
+# . Ad Hour Reports
+class AdHourData(Parameter):
+    """查询广告的小时报告参数"""
+
+    # 报告日期 (只能查询最近60天内的数据)
+    report_date: str
+    # 广告活动ID
+    campaign_id: NonNegativeInt
+    # 聚合纬度
+    agg_dimension: Optional[NonEmptyStr] = None
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("report_date", mode="before")
+    @classmethod
+    def _validate_report_date(cls, v: str) -> str:
+        dt = utils.validate_datetime(v, False, "广告报告日期")
+        return "%04d-%02d-%02d" % (dt.year, dt.month, dt.day)
+
+
+# . SB Target Reports
+class SbTargetingReports(AdReports):
+    """查询 SB 广告投放目标报告参数"""
+
+    # SB广告类型 ('SB', 'SBV', 'ALL')
+    ad_type: NonEmptyStr = Field(alias="sponsored_type")
+    # 投放目标类型 ('keyword', 'product', 'ALL')
+    targeting_type: NonEmptyStr = Field(alias="target_type")
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("targeting_type", mode="before")
+    @classmethod
+    def _validate_targeting_type(cls, v: str) -> str:
+        return "producttarget" if v == "product" else v
+
+
+# . SB Query Word Reports
+class SbQueryWordReports(AdReports):
+    """查询 SB 用户搜索词报告参数"""
+
+    targeting_type: NonEmptyStr = Field(alias="target_type")
+
+
+# . DSP Reports
+class DspReports(PageOffestAndLength):
+    """查询 DSP 报告参数"""
+
+    # 开始日期, 双闭区间, 时间间隔最长不超过90天
+    start_date: str
+    # 结束日期, 双闭区间, 时间间隔最长不超过90天
+    end_date: str
+    # 亚马逊店铺ID [广告帐号ID] (AdsProfiles.profile_id)
+    profile_id: NonNegativeInt
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("start_date", "end_date", mode="before")
+    @classmethod
+    def _validate_date(cls, v: str, info: ValidationInfo) -> str:
+        dt = utils.validate_datetime(v, False, "DSP报告日期 %s" % info.field_name)
+        return "%04d-%02d-%02d" % (dt.year, dt.month, dt.day)
+
+
+# 报表下载 ----------------------------------------------------------------------------------------------------------------------
+# . Download ABA Report
+class DownloadAbaReport(Parameter):
+    """查询 Amazon ABA 报表下载参数"""
+
+    # 国家代码
+    country_code: CountryCode = Field(alias="country")
+    # 开始日期, 报表开始日期, 自动会调整为当周周日
+    start_date: str = Field(alias="data_start_time")
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("start_date", mode="before")
+    @classmethod
+    def _validate_start_date(cls, v: str) -> str:
+        dt = utils.validate_datetime(v, False, "ABA报表开始日期").to_sunday()
+        return "%04d-%02d-%02d" % (dt.year, dt.month, dt.day)
+
+
+# 操作日志 ----------------------------------------------------------------------------------------------------------------------
+# . Ads Operation Logs
+class AdsOperationLogs(PageOffestAndLength):
+    """查询广告操作日志参数"""
+
+    # 领星店铺ID
+    sid: NonNegativeInt
+    # 开始日期, 日期间隔不能超过1个月
+    start_date: str
+    # 结束日期, 日期间隔不能超过1个月
+    end_date: str
+    # 广告类型 ('sp', 'sb', 'sd')
+    ad_type: str = Field(alias="sponsored_type")
+    # 操作对象
+    # - campaigns 广告活动
+    # - adGroups 广告组
+    # - productAds 广告
+    # - keywords 关键词
+    # - negativeKeywords 否定关键词
+    # - targets 商品投放
+    # - negativeTargets 否定商品投放
+    # - profiles 预算设置
+    operation_target: NonEmptyStr = Field(alias="operate_type")
+    # 日志来源
+    log_source: NonEmptyStr
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("start_date", "end_date", mode="before")
+    @classmethod
+    def _validate_date(cls, v: str, info: ValidationInfo) -> str:
+        dt = utils.validate_datetime(v, False, "广告操作日志日期 %s" % info.field_name)
+        return "%04d-%02d-%02d" % (dt.year, dt.month, dt.day)
+
+    @field_validator("ad_type", mode="before")
+    @classmethod
+    def _validate_ad_type(cls, v) -> str:
+        if not isinstance(v, str):
+            raise ValueError("广告类型必须是字符串")
+        return v.lower()

lingxingapi/ads/route.py

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+
+# fmt: off
+# 基础数据 ----------------------------------------------------------------------------------------------------------------------
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/dspAccountList
+AD_PROFILES: str = "/basicOpen/baseData/account/list"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/portfolios
+PORTFOLIOS: str = "/pb/openapi/newad/portfolios"
+
+# . 基础数据 - Sponsored Products
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/spCampaigns
+SP_CAMPAIGNS: str = "/pb/openapi/newad/spCampaigns"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/spAdGroups
+SP_AD_GROUPS: str = "/pb/openapi/newad/spAdGroups"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/spProductAds
+SP_PRODUCTS: str = "/pb/openapi/newad/spProductAds"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/spKeywords
+SP_KEYWORDS: str = "/pb/openapi/newad/spKeywords"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/spTargets
+SP_TARGETS: str = "/pb/openapi/newad/spTargets"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/spNegativeTargetsOrKeywords
+SP_NEGATIVE_TARGETING: str = "/pb/openapi/newad/spNegativeTargetsOrKeywords"
+
+# . 基础数据 - Sponsored Brands
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/hsaCampaigns
+SB_CAMPAIGNS: str = "/pb/openapi/newad/hsaCampaigns"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/hsaAdGroups
+SB_AD_GROUPS: str = "/pb/openapi/newad/hsaAdGroups"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/sbAdHasProductAds
+SB_CREATIVES: str = "/pb/openapi/newad/hsaProductAds"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/sbTargeting
+SB_TARGETING: str = "/pb/openapi/newad/sbTargeting"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/hsaNegativeKeywords
+SB_NEGATIVE_KEYWORDS: str = "/pb/openapi/newad/hsaNegativeKeywords"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/hsaNegativeTargets
+SB_NEGATIVE_TARGETS: str = "/pb/openapi/newad/hsaNegativeTargets"
+
+# . 基础数据 - Sponsored Display
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/sdCampaigns
+SD_CAMPAIGNS: str = "/pb/openapi/newad/sdCampaigns"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/sdAdGroups
+SD_AD_GROUPS: str = "/pb/openapi/newad/sdAdGroups"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/sdProductAds
+SD_PRODUCTS: str = "/pb/openapi/newad/sdProductAds"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/sdTargets
+SD_TARGETS: str = "/pb/openapi/newad/sdTargets"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/sdNegativeTargets
+SD_NEGATIVE_TARGETS: str = "/pb/openapi/newad/sdNegativeTargets"
+
+# 报告 -------------------------------------------------------------------------------------------------------------------------
+# . 报告 - Sponsored Products
+# https://apidoc.lingxing.com/#/docs/newAd/report/spCampaignReports
+SP_CAMPAIGN_REPORTS: str = "/pb/openapi/newad/spCampaignReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/spCampaignHourData
+SP_CAMPAIGN_HOUR_DATA: str = "/pb/openapi/newad/spCampaignHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/campaignPlacementReports
+SP_PLACEMENT_REPORTS: str = "/pb/openapi/newad/campaignPlacementReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/spAdPlacementHourData
+SP_PLACEMENT_HOUR_DATA: str = "/pb/openapi/newad/spAdPlacementHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/spAdGroupReports
+SP_AD_GROUP_REPORTS: str = "/pb/openapi/newad/spAdGroupReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/spAdGroupHourData
+SP_AD_GROUP_HOUR_DATA: str = "/pb/openapi/newad/spAdGroupHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/spProductAdReports
+SP_PRODUCT_REPORTS: str = "/pb/openapi/newad/spProductAdReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/spAdvertiseHourData
+SP_PRODUCT_KEYWORD_HOUR_DATA: str = "/pb/openapi/newad/spAdvertiseHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/spKeywordReports
+SP_KEYWORD_REPORTS: str = "/pb/openapi/newad/spKeywordReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/spTargetReports
+SP_TARGET_REPORTS: str = "/pb/openapi/newad/spTargetReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/spTargetHourData
+SP_TARGET_HOUR_DATA: str = "/pb/openapi/newad/spTargetHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/queryWordReports
+SP_QUERY_WORD_REPORTS: str = "/pb/openapi/newad/queryWordReports"
+
+# . 报告 - Sponsored Brands
+# https://apidoc.lingxing.com/#/docs/newAd/report/hsaCampaignReports
+SB_CAMPAIGN_REPORTS: str = "/pb/openapi/newad/hsaCampaignReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sbCampaignHourData
+SB_CAMPAIGN_HOUR_DATA: str = "/pb/openapi/newad/sbCampaignHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/hsaCampaignPlacementReports
+SB_PLACEMENT_REPORTS: str = "/pb/openapi/newad/hsaCampaignPlacementReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sbAdPlacementHourData
+SB_PLACEMENT_HOUR_DATA: str = "/pb/openapi/newad/sbAdPlacementHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/hsaAdGroupReports
+SB_AD_GROUP_REPORTS: str = "/pb/openapi/newad/hsaAdGroupReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sbAdGroupHourData
+SB_AD_GROUP_HOUR_DATA: str = "/pb/openapi/newad/sbAdGroupHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/listHsaProductAdReport
+SB_CREATIVE_REPORTS: str = "/pb/openapi/newad/listHsaProductAdReport"
+# https://apidoc.lingxing.com/#/docs/newAd/report/listHsaTargetingReport
+SB_TARGETING_REPORTS: str = "/pb/openapi/newad/listHsaTargetingReport"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sbTargetHourData
+SB_TARGETING_HOUR_DATA: str = "/pb/openapi/newad/sbTargetHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/hsaQueryWordReports
+SB_QUERY_WORD_REPORTS: str = "/pb/openapi/newad/hsaQueryWordReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/hsaPurchasedAsinReports
+SB_ASIN_ATTRIBUTION_REPORTS: str = "/pb/openapi/newad/hsaPurchasedAsinReports"
+# https://apidoc.lingxing.com/#/docs/newAd/baseData/newadsbDivideAsinReports
+SB_COST_ALLOCATION_REPORTS: str = "/pb/openapi/newad/sbDivideAsinReports"
+
+# . 报告 - Sponsored Display
+# https://apidoc.lingxing.com/#/docs/newAd/report/sdCampaignReports
+SD_CAMPAIGN_REPORTS: str = "/pb/openapi/newad/sdCampaignReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sdCampaignHourData
+SD_CAMPAIGN_HOUR_DATA: str = "/pb/openapi/newad/sdCampaignHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sdAdGroupReports
+SD_AD_GROUP_REPORTS: str = "/pb/openapi/newad/sdAdGroupReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sdAdGroupHourData
+SD_AD_GROUP_HOUR_DATA: str = "/pb/openapi/newad/sdAdGroupHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sdProductAdReports
+SD_PRODUCT_REPORTS: str = "/pb/openapi/newad/sdProductAdReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sdAdvertiseHourData
+SD_PRODUCT_HOUR_DATA: str = "/pb/openapi/newad/sdAdvertiseHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sdTargetReports
+SD_TARGET_REPORTS: str = "/pb/openapi/newad/sdTargetReports"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sdTargetHourData
+SD_TARGET_HOUR_DATA: str = "/pb/openapi/newad/sdTargetHourData"
+# https://apidoc.lingxing.com/#/docs/newAd/report/sdMatchTargetReports
+SD_MATCHED_TARGET_REPORTS: str = "/pb/openapi/newad/sdMatchTargetReports"
+
+# . 报告 - Demand-Side Platform (DSP)
+# https://apidoc.lingxing.com/#/docs/newAd/report/dspReportOrderList
+DSP_REPORTS: str = "/basicOpen/dspReport/order/list"
+
+
+# 报表下载 ----------------------------------------------------------------------------------------------------------------------
+# https://apidoc.lingxing.com/#/docs/newAd/reportDownload/abaReport
+DOWNLOAD_ABA_REPORT: str = "/pb/openapi/newad/abaReport"
+
+# 操作日志 ----------------------------------------------------------------------------------------------------------------------
+# https://apidoc.lingxing.com/#/docs/newAd/apiLogStandard
+ADS_OPERATION_LOGS: str = "/pb/openapi/newad/apiLogStandard"