Python ya-direct-api 包完整使用指南ya-direct-api是俄罗斯Yandex.Direct广告平台的官方Python SDK专门用于对接Yandex.Direct广告API实现广告账户、广告组、关键词、投放数据、报表等全流程自动化管理是Yandex广告投放自动化、数据分析、批量操作的核心工具包。它基于Yandex.DirectV5版本API开发封装了API的认证、请求、响应解析逻辑无需手动处理HTTP请求、签名、Token刷新等繁琐操作大幅降低开发成本。一、核心功能账户管理查询广告主账户信息、余额、权限、账户状态广告资源管理批量创建/修改/删除广告组、广告创意、关键词、投放地域数据统计获取广告曝光、点击、消费、转化、ROI等实时/历史数据报表生成导出自定义维度日/周/月、账户/组/关键词的统计报表出价管理自动调整关键词出价、竞价策略配置自动化操作批量暂停/启用广告、异常监控、数据同步完整API覆盖支持Yandex.Direct V5 API所有接口和参数二、安装方法1. 基础安装pip# 标准安装pipinstallya-direct-api# 指定版本安装推荐稳定版pipinstallya-direct-api1.0.12. 依赖说明依赖包requestsHTTP请求、pyjwt令牌认证、python-dotenv环境变量安装时会自动预装。3. 验证安装importyadirect_apiprint(yadirect_api.__version__)# 输出版本号即安装成功三、核心语法与基础参数1. 初始化客户端核心语法所有操作都需要先初始化API客户端这是使用的第一步。fromyadirect_apiimportYandexDirectApi# 初始化客户端clientYandexDirectApi(token你的OAuth2令牌,# 必传API访问令牌login广告账户登录名,# 必传Yandex广告账户登录名localeru# 可选语言ru/en/tr等默认ru)2. 核心参数说明参数名类型必传说明tokenstr是Yandex.Direct API OAuth2授权令牌loginstr是广告账户登录名账户中心IDlocalestr否返回数据语言支持ru/en/trtimeoutint否请求超时时间默认30秒3. 通用调用语法# 调用API接口格式client.接口模块.方法(参数)responseclient.{模块}.{方法}(参数字典)# 示例获取广告账户信息responseclient.accounts.get({FieldNames:[Login,AccountQuality,Balance]})4. 通用请求参数所有接口通用的基础参数FieldNames列表指定需要返回的字段必填减少数据传输SelectionCriteria字典筛选条件ID、状态、时间等Limitint限制返回数据条数Offsetint数据偏移量分页用四、8个实际应用案例所有案例均为可直接运行的完整代码替换token和login即可使用。案例1查询广告账户基础信息余额用途监控账户余额、账户质量、状态fromyadirect_apiimportYandexDirectApi# 初始化clientYandexDirectApi(tokenYOUR_TOKEN,loginYOUR_LOGIN)# 请求参数指定需要查询的字段params{FieldNames:[Login,Balance,AccountQuality,Status]}# 调用接口resultclient.accounts.get(params)# 输出结果print(账户余额,result[result][Accounts][0][Balance])print(账户状态,result[result][Accounts][0][Status])案例2批量获取广告组列表用途导出所有广告组名称、状态、预算params{FieldNames:[Id,Name,Status,CampaignId,Budget],SelectionCriteria:{Statuses:[ACCEPTED,DRAFT]# 筛选状态已启用/草稿}}resultclient.adgroups.get(params)forgroupinresult[result][AdGroups]:print(f广告组ID{group[Id]}, 名称{group[Name]}, 状态{group[Status]})案例3批量查询关键词数据用途获取关键词出价、点击量、状态params{FieldNames:[Id,Keyword,Bid,Clicks,Status],SelectionCriteria:{AdGroupIds:[123456,789012]# 指定广告组ID}}resultclient.keywords.get(params)forkwinresult[result][Keywords]:print(f关键词{kw[Keyword]}, 出价{kw[Bid]}, 点击量{kw[Clicks]})案例4获取广告日度统计报表用途自动化导出每日曝光、点击、消费数据params{DateRangeType:CUSTOM_DATE,# 自定义时间范围DateFrom:2025-01-01,DateTo:2025-01-10,FieldNames:[Date,Impressions,Clicks,Cost,Ctr],GroupBy:[Date]# 按日期分组}resultclient.reports.get_summary(params)foriteminresult[result][Rows]:print(f日期{item[Date]}, 曝光{item[Impressions]}, 消费{item[Cost]})案例5批量修改关键词出价用途自动化调价提升投放效率# 批量更新出价ID111的关键词出价设为150ID222设为200params{Keywords:[{Id:111,Bid:1500000},# 单位1/1000000卢布{Id:222,Bid:2000000}]}resultclient.keywords.update(params)print(更新结果,result)注意出价单位为1/1000000卢布1卢布1000000单位案例6暂停/启用广告组用途根据效果自动启停广告组# 暂停指定广告组params{SelectionCriteria:{Ids:[123456]},Status:PAUSED# PAUSED暂停ENABLED启用}resultclient.adgroups.suspend(params)print(广告组已暂停)案例7创建新广告组用途批量新建广告组params{AdGroups:[{CampaignId:987654,# 广告系列IDName:Python自动化创建-测试组,Status:DRAFT}]}resultclient.adgroups.add(params)print(新建广告组ID,result[result][AdGroups][0][Id])案例8获取广告创意列表与状态用途监控创意审核状态、点击率params{FieldNames:[Id,Title,Text,Status,Ctr],SelectionCriteria:{AdGroupIds:[123456]}}resultclient.ads.get(params)foradinresult[result][Ads]:print(f创意标题{ad[Title]}, 审核状态{ad[Status]}, CTR{ad[Ctr]})五、常见错误与解决方案1.Token invalid/expired令牌无效/过期原因OAuth令牌过期、错误、权限不足解决重新生成Yandex API令牌确保授予ydirectapi权限2.Login not found账户不存在原因login参数填写错误不是广告账户登录名解决在Yandex.Direct后台复制账户登录名而非邮箱3.FieldNames is required缺少必填字段原因所有查询接口必须指定FieldNames解决补充需要返回的字段列表4.Bid value invalid出价格式错误原因出价单位错误必须是1/1000000卢布解决出价目标卢布数 × 10000005.API rate limit exceeded请求频率超限原因Yandex API限制每秒请求数解决添加延时time.sleep(1)批量操作分批请求6.Permission denied权限不足原因令牌未获取操作权限解决重新授权勾选所有操作权限六、使用注意事项令牌安全不要将token硬编码在代码中推荐使用环境变量/配置文件令牌定期更换避免泄露数据单位金额单位为1/1000000卢布必须换算出价、预算都遵循该规则请求频率限制Yandex API限制10次/秒批量操作必须分批延时大量数据用LimitOffset分页获取字段权限不是所有字段都能随意查询需账户权限匹配优先查询公开字段Id/Name/Status/Clicks等状态枚举值广告状态ENABLED(启用)、PAUSED(暂停)、DRAFT(草稿)必须严格使用官方枚举值不能自定义异常处理生产环境必须添加try-except捕获API异常示例try:resultclient.accounts.get(params)exceptExceptionase:print(API请求失败,str(e))语言与时区默认语言ru需要英文设置localeen时间默认使用莫斯科时区报表需手动转换测试环境正式操作前用测试账户验证代码避免直接操作生产广告账户导致误删/误改总结ya-direct-api是Yandex广告自动化的官方Python SDK覆盖全功能API操作核心步骤安装→初始化客户端→调用接口→处理响应8个案例覆盖账户、广告组、关键词、报表、调价、启停、创建、创意全场景核心注意事项令牌安全、出价单位、请求频率、异常处理、状态枚举生产环境务必做好权限控制和异常捕获避免广告投放事故《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。
Python之ya-direct-api包语法、参数和实际应用案例
发布时间：2026/6/4 9:10:39
Python ya-direct-api 包完整使用指南ya-direct-api是俄罗斯Yandex.Direct广告平台的官方Python SDK专门用于对接Yandex.Direct广告API实现广告账户、广告组、关键词、投放数据、报表等全流程自动化管理是Yandex广告投放自动化、数据分析、批量操作的核心工具包。它基于Yandex.DirectV5版本API开发封装了API的认证、请求、响应解析逻辑无需手动处理HTTP请求、签名、Token刷新等繁琐操作大幅降低开发成本。一、核心功能账户管理查询广告主账户信息、余额、权限、账户状态广告资源管理批量创建/修改/删除广告组、广告创意、关键词、投放地域数据统计获取广告曝光、点击、消费、转化、ROI等实时/历史数据报表生成导出自定义维度日/周/月、账户/组/关键词的统计报表出价管理自动调整关键词出价、竞价策略配置自动化操作批量暂停/启用广告、异常监控、数据同步完整API覆盖支持Yandex.Direct V5 API所有接口和参数二、安装方法1. 基础安装pip# 标准安装pipinstallya-direct-api# 指定版本安装推荐稳定版pipinstallya-direct-api1.0.12. 依赖说明依赖包requestsHTTP请求、pyjwt令牌认证、python-dotenv环境变量安装时会自动预装。3. 验证安装importyadirect_apiprint(yadirect_api.__version__)# 输出版本号即安装成功三、核心语法与基础参数1. 初始化客户端核心语法所有操作都需要先初始化API客户端这是使用的第一步。fromyadirect_apiimportYandexDirectApi# 初始化客户端clientYandexDirectApi(token你的OAuth2令牌,# 必传API访问令牌login广告账户登录名,# 必传Yandex广告账户登录名localeru# 可选语言ru/en/tr等默认ru)2. 核心参数说明参数名类型必传说明tokenstr是Yandex.Direct API OAuth2授权令牌loginstr是广告账户登录名账户中心IDlocalestr否返回数据语言支持ru/en/trtimeoutint否请求超时时间默认30秒3. 通用调用语法# 调用API接口格式client.接口模块.方法(参数)responseclient.{模块}.{方法}(参数字典)# 示例获取广告账户信息responseclient.accounts.get({FieldNames:[Login,AccountQuality,Balance]})4. 通用请求参数所有接口通用的基础参数FieldNames列表指定需要返回的字段必填减少数据传输SelectionCriteria字典筛选条件ID、状态、时间等Limitint限制返回数据条数Offsetint数据偏移量分页用四、8个实际应用案例所有案例均为可直接运行的完整代码替换token和login即可使用。案例1查询广告账户基础信息余额用途监控账户余额、账户质量、状态fromyadirect_apiimportYandexDirectApi# 初始化clientYandexDirectApi(tokenYOUR_TOKEN,loginYOUR_LOGIN)# 请求参数指定需要查询的字段params{FieldNames:[Login,Balance,AccountQuality,Status]}# 调用接口resultclient.accounts.get(params)# 输出结果print(账户余额,result[result][Accounts][0][Balance])print(账户状态,result[result][Accounts][0][Status])案例2批量获取广告组列表用途导出所有广告组名称、状态、预算params{FieldNames:[Id,Name,Status,CampaignId,Budget],SelectionCriteria:{Statuses:[ACCEPTED,DRAFT]# 筛选状态已启用/草稿}}resultclient.adgroups.get(params)forgroupinresult[result][AdGroups]:print(f广告组ID{group[Id]}, 名称{group[Name]}, 状态{group[Status]})案例3批量查询关键词数据用途获取关键词出价、点击量、状态params{FieldNames:[Id,Keyword,Bid,Clicks,Status],SelectionCriteria:{AdGroupIds:[123456,789012]# 指定广告组ID}}resultclient.keywords.get(params)forkwinresult[result][Keywords]:print(f关键词{kw[Keyword]}, 出价{kw[Bid]}, 点击量{kw[Clicks]})案例4获取广告日度统计报表用途自动化导出每日曝光、点击、消费数据params{DateRangeType:CUSTOM_DATE,# 自定义时间范围DateFrom:2025-01-01,DateTo:2025-01-10,FieldNames:[Date,Impressions,Clicks,Cost,Ctr],GroupBy:[Date]# 按日期分组}resultclient.reports.get_summary(params)foriteminresult[result][Rows]:print(f日期{item[Date]}, 曝光{item[Impressions]}, 消费{item[Cost]})案例5批量修改关键词出价用途自动化调价提升投放效率# 批量更新出价ID111的关键词出价设为150ID222设为200params{Keywords:[{Id:111,Bid:1500000},# 单位1/1000000卢布{Id:222,Bid:2000000}]}resultclient.keywords.update(params)print(更新结果,result)注意出价单位为1/1000000卢布1卢布1000000单位案例6暂停/启用广告组用途根据效果自动启停广告组# 暂停指定广告组params{SelectionCriteria:{Ids:[123456]},Status:PAUSED# PAUSED暂停ENABLED启用}resultclient.adgroups.suspend(params)print(广告组已暂停)案例7创建新广告组用途批量新建广告组params{AdGroups:[{CampaignId:987654,# 广告系列IDName:Python自动化创建-测试组,Status:DRAFT}]}resultclient.adgroups.add(params)print(新建广告组ID,result[result][AdGroups][0][Id])案例8获取广告创意列表与状态用途监控创意审核状态、点击率params{FieldNames:[Id,Title,Text,Status,Ctr],SelectionCriteria:{AdGroupIds:[123456]}}resultclient.ads.get(params)foradinresult[result][Ads]:print(f创意标题{ad[Title]}, 审核状态{ad[Status]}, CTR{ad[Ctr]})五、常见错误与解决方案1.Token invalid/expired令牌无效/过期原因OAuth令牌过期、错误、权限不足解决重新生成Yandex API令牌确保授予ydirectapi权限2.Login not found账户不存在原因login参数填写错误不是广告账户登录名解决在Yandex.Direct后台复制账户登录名而非邮箱3.FieldNames is required缺少必填字段原因所有查询接口必须指定FieldNames解决补充需要返回的字段列表4.Bid value invalid出价格式错误原因出价单位错误必须是1/1000000卢布解决出价目标卢布数 × 10000005.API rate limit exceeded请求频率超限原因Yandex API限制每秒请求数解决添加延时time.sleep(1)批量操作分批请求6.Permission denied权限不足原因令牌未获取操作权限解决重新授权勾选所有操作权限六、使用注意事项令牌安全不要将token硬编码在代码中推荐使用环境变量/配置文件令牌定期更换避免泄露数据单位金额单位为1/1000000卢布必须换算出价、预算都遵循该规则请求频率限制Yandex API限制10次/秒批量操作必须分批延时大量数据用LimitOffset分页获取字段权限不是所有字段都能随意查询需账户权限匹配优先查询公开字段Id/Name/Status/Clicks等状态枚举值广告状态ENABLED(启用)、PAUSED(暂停)、DRAFT(草稿)必须严格使用官方枚举值不能自定义异常处理生产环境必须添加try-except捕获API异常示例try:resultclient.accounts.get(params)exceptExceptionase:print(API请求失败,str(e))语言与时区默认语言ru需要英文设置localeen时间默认使用莫斯科时区报表需手动转换测试环境正式操作前用测试账户验证代码避免直接操作生产广告账户导致误删/误改总结ya-direct-api是Yandex广告自动化的官方Python SDK覆盖全功能API操作核心步骤安装→初始化客户端→调用接口→处理响应8个案例覆盖账户、广告组、关键词、报表、调价、启停、创建、创意全场景核心注意事项令牌安全、出价单位、请求频率、异常处理、状态枚举生产环境务必做好权限控制和异常捕获避免广告投放事故《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。
