Python之ya-direct-api包语法、参数和实际应用案例

Python ya-direct-api 包完整使用指南

ya-direct-api 是俄罗斯Yandex.Direct广告平台的官方Python SDK，专门用于对接Yandex.Direct广告API，实现广告账户、广告组、关键词、投放数据、报表等全流程自动化管理，是Yandex广告投放自动化、数据分析、批量操作的核心工具包。

它基于Yandex.Direct V5版本API开发，封装了API的认证、请求、响应解析逻辑，无需手动处理HTTP请求、签名、Token刷新等繁琐操作，大幅降低开发成本。

一、核心功能

二、安装方法

1. 基础安装（pip）

# 标准安装
pip install ya-direct-api

# 指定版本安装（推荐稳定版）
pip install ya-direct-api==1.0.1

2. 依赖说明

依赖包：requests（HTTP请求）、pyjwt（令牌认证）、python-dotenv（环境变量），安装时会自动预装。

3. 验证安装

import yadirect_api
print(yadirect_api.__version__) # 输出版本号即安装成功

三、核心语法与基础参数

1. 初始化客户端（核心语法）

所有操作都需要先初始化API客户端，这是使用的第一步。

from yadirect_api import YandexDirectApi

# 初始化客户端
client = YandexDirectApi(
token="你的OAuth2令牌", # 必传：API访问令牌
login="广告账户登录名", # 必传：Yandex广告账户登录名
locale="ru" # 可选：语言（ru/en/tr等），默认ru
)

2. 核心参数说明

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：查询广告账户基础信息+余额

用途：监控账户余额、账户质量、状态

from yadirect_api import YandexDirectApi

# 初始化
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)
for group in result["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)
for kw in result["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)
for item in result["result"]["Rows"]:
print(f"日期：{item['Date']}, 曝光：{item['Impressions']}, 消费：{item['Cost']}")

案例5：批量修改关键词出价

用途：自动化调价，提升投放效率

# 批量更新出价：ID=111的关键词出价设为150，ID=222设为200
params = {
"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)
for ad in result["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（权限不足）

• 原因：令牌未获取操作权限
• 解决：重新授权，勾选所有操作权限

六、使用注意事项

总结

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。