Python之ya-direct-api包语法、参数和实际应用案例
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-api==1.0.12. 依赖说明
依赖包：requests（HTTP请求）、pyjwt（令牌认证）、python-dotenv（环境变量），安装时会自动预装。
3. 验证安装
importyadirect_apiprint(yadirect_api.__version__)# 输出版本号即安装成功三、核心语法与基础参数
1. 初始化客户端（核心语法）
所有操作都需要先初始化API客户端，这是使用的第一步。
fromyadirect_apiimportYandexDirectApi# 初始化客户端client=YandexDirectApi(token="你的OAuth2令牌",# 必传：API访问令牌login="广告账户登录名",# 必传：Yandex广告账户登录名locale="ru"# 可选：语言（ru/en/tr等），默认ru)2. 核心参数说明
| 参数名 | 类型 | 必传 | 说明 |
|---|---|---|---|
token | str | 是 | Yandex.Direct API OAuth2授权令牌 |
login | str | 是 | 广告账户登录名（账户中心ID） |
locale | str | 否 | 返回数据语言，支持ru/en/tr |
timeout | int | 否 | 请求超时时间，默认30秒 |
3. 通用调用语法
# 调用API接口格式：client.接口模块.方法(参数)response=client.{模块}.{方法}(参数字典)# 示例：获取广告账户信息response=client.accounts.get({"FieldNames":["Login","AccountQuality","Balance"]})4. 通用请求参数
所有接口通用的基础参数：
FieldNames：列表，指定需要返回的字段（必填，减少数据传输）SelectionCriteria：字典，筛选条件（ID、状态、时间等）Limit：int，限制返回数据条数Offset：int，数据偏移量（分页用）
四、8个实际应用案例
所有案例均为可直接运行的完整代码，替换token和login即可使用。
案例1：查询广告账户基础信息+余额
用途：监控账户余额、账户质量、状态
fromyadirect_apiimportYandexDirectApi# 初始化client=YandexDirectApi(token="YOUR_TOKEN",login="YOUR_LOGIN")# 请求参数：指定需要查询的字段params={"FieldNames":["Login","Balance","AccountQuality","Status"]}# 调用接口result=client.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"]# 筛选状态：已启用/草稿}}result=client.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}}result=client.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"]# 按日期分组}result=client.reports.get_summary(params)foriteminresult["result"]["Rows"]:print(f"日期：{item['Date']}, 曝光：{item['Impressions']}, 消费：{item['Cost']}")案例5：批量修改关键词出价
用途：自动化调价，提升投放效率
# 批量更新出价：ID=111的关键词出价设为150，ID=222设为200params={"Keywords":[{"Id":111,"Bid":1500000},# 单位：1/1000000卢布{"Id":222,"Bid":2000000}]}result=client.keywords.update(params)print("更新结果：",result)注意：出价单位为1/1000000卢布，1卢布=1000000单位
案例6：暂停/启用广告组
用途：根据效果自动启停广告组
# 暂停指定广告组params={"SelectionCriteria":{"Ids":[123456]},"Status":"PAUSED"# PAUSED=暂停，ENABLED=启用}result=client.adgroups.suspend(params)print("广告组已暂停")案例7：创建新广告组
用途：批量新建广告组
params={"AdGroups":[{"CampaignId":987654,# 广告系列ID"Name":"Python自动化创建-测试组","Status":"DRAFT"}]}result=client.adgroups.add(params)print("新建广告组ID：",result["result"]["AdGroups"][0]["Id"])案例8：获取广告创意列表与状态
用途：监控创意审核状态、点击率
params={"FieldNames":["Id","Title","Text","Status","Ctr"],"SelectionCriteria":{"AdGroupIds":[123456]}}result=client.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卢布）
- 解决：出价=目标卢布数 × 1000000
5.API rate limit exceeded（请求频率超限）
- 原因：Yandex API限制每秒请求数
- 解决：添加延时
time.sleep(1)，批量操作分批请求
6.Permission denied（权限不足）
- 原因：令牌未获取操作权限
- 解决：重新授权，勾选所有操作权限
六、使用注意事项
令牌安全
- 不要将
token硬编码在代码中，推荐使用环境变量/配置文件 - 令牌定期更换，避免泄露
- 不要将
数据单位
- 金额：单位为1/1000000卢布，必须换算
- 出价、预算都遵循该规则
请求频率限制
- Yandex API限制：10次/秒，批量操作必须分批+延时
- 大量数据用
Limit+Offset分页获取
字段权限
- 不是所有字段都能随意查询，需账户权限匹配
- 优先查询公开字段：
Id/Name/Status/Clicks等
状态枚举值
- 广告状态：
ENABLED(启用)、PAUSED(暂停)、DRAFT(草稿) - 必须严格使用官方枚举值，不能自定义
- 广告状态：
异常处理
- 生产环境必须添加
try-except捕获API异常 - 示例：
try:result=client.accounts.get(params)exceptExceptionase:print("API请求失败：",str(e))
- 生产环境必须添加
语言与时区
- 默认语言
ru，需要英文设置locale="en" - 时间默认使用莫斯科时区，报表需手动转换
- 默认语言
测试环境
- 正式操作前，用测试账户验证代码
- 避免直接操作生产广告账户导致误删/误改
总结
ya-direct-api是Yandex广告自动化的官方Python SDK，覆盖全功能API操作- 核心步骤：安装→初始化客户端→调用接口→处理响应
- 8个案例覆盖账户、广告组、关键词、报表、调价、启停、创建、创意全场景
- 核心注意事项：令牌安全、出价单位、请求频率、异常处理、状态枚举
- 生产环境务必做好权限控制和异常捕获，避免广告投放事故
《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。