
Naver Ad Performance Skill 实战指南用 k-skill 查询 Naver 搜索广告投放效果【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skillNaver 搜索广告검색광고的投放效果数据可以通过官方 API 获取但认证流程HMAC-SHA256 签名与多种查询端点容易让开发者望而却步。k-skill 仓库中的naver-ad-performance技能以 Python 标准库封装了这套 API提供诊断、结构查询、周期绩效查询与关键词工具四个子命令全程只读、无需额外安装任何第三方包。阅读本文后你将掌握该技能的完整使用方法包括 API 密钥签发、签名算法原理、CLI 命令详解、返回字段语义以及常见失败模式的排查思路并能结合源码理解其底层实现细节。功能总览这个技能能做什么naver-ad-performance是 k-skill 中面向 Naver 搜索广告关键词广告账号的只读查询技能。它围绕官方 API 提供四类能力结构查询拉取账户下的 广告系列campaign/广告组adgroup/关键词keyword列表周期绩效查询按日期区间查询 曝光数impCnt、点击数clkCnt、广告费salesAmt、CTR、CPC、平均曝光排名avgRnk、转化数ccnt并支持按日--by day细分关键词工具查询关联关键词、月度 PC/移动端搜索量、竞争程度等选词数据环境诊断通过doctor子命令检查三个环境变量是否配置齐全以及本机到api.searchad.naver.com的网络可达性。需要特别强调的是该技能没有任何写操作不会修改出价입찰가、不会创建/修改/删除广告系列与关键词也不会变更预算或切换投放状态。这种查询与写操作隔离是刻意的安全设计详见下文只读边界小节。技能元数据可在 skill.json 中看到其类别为marketing语言为ko-KR授权协议为 MIT。完整的运行时指令以 instruction.md 为准本文是围绕 功能特性文档 展开的实战解读。前置条件账号、密钥与运行环境使用前需要准备三样东西网络可达性Naver 搜索广告 API 要求本地网络出口egress能访问api.searchad.naver.com。在云沙箱sandbox等采用域名白名单机制的运行环境里出口可能被阻断导致请求失败——此时应改用本地执行环境。Python 3.9脚本 naver_ad_performance.py 仅依赖 Python 标准库urllib、hmac、hashlib、base64、argparse等不需要pip install任何额外包。API 密钥三件套登录 Naver 搜索广告后台searchad.naver.com进入도구工具 API 사용 관리API 使用管理签发 API Key 与 Secret同时获取你的CUSTOMER_ID然后通过三个环境变量注入脚本环境变量含义NAVER_AD_API_KEYNaver 搜索广告 API 密钥NAVER_AD_SECRET_KEY签名用密钥用于 HMAC-SHA256NAVER_AD_CUSTOMER_ID广告客户customer标识关于密钥的保管instruction.md 给出了运行时层面的安全约定在 Dolshoi 运行时中代理应通过预置的vault-run能力让密钥不经过模型可见若缺失则调用request_vault_credential唤起应用内的 vault 输入界面。在 generic 回退模式下则按 环境变量 → host vault →secrets.env的顺序解析。无论如何都不应在对话或命令行参数中明文打印密钥。官方 API 表面端点与认证协议技能直接对接 Naver 搜索广告公开 API相关常量定义在源码 naver_ad_performance.pyBase URLhttps://api.searchad.naver.com绩效查询GET /stats结构查询GET /ncc/campaigns、GET /ncc/adgroups、GET /ncc/keywords关键词工具GET /keywordstool每一次请求都需要携带四个认证相关的 HTTP 头源码见 request()Header说明X-Timestamp当前毫秒级 epoch 时间戳X-API-KEY前面签发的 API KeyX-CustomerCUSTOMER_IDX-SignatureHMAC-SHA256 签名结果base64 编码签名消息的构造规则是核心官方约定为message {timestamp}.{method}.{uri_path_only} # 不含查询字符串method 大写 signature base64(HMAC_SHA256(message, SECRET_KEY))源码中的 build_signature() 正是这条规则的直接实现。一个值得注意的细节是签名消息只包含 URI 路径不含查询字符串。测试用例 test_request_signature_excludes_query_string_from_message 专门验证了这一点——即使请求 URL 带上了?ids...fields...查询参数签名仍基于裸路径/stats计算。这也就解释了为什么签名要按先拼 URL 路径、后追加参数的顺序生成。CLI 使用指南从诊断到查询所有命令都通过 k-skill CLI 统一入口执行通用形式为npx -y nomadamas/k-skill0 exec naver-ad-performance scripts/naver_ad_performance.py -- 子命令 参数CLI 子命令由argparse定义详见 build_parser()。下面按实际工作流逐一讲解。第一步环境诊断doctornpx -y nomadamas/k-skill0 exec naver-ad-performance scripts/naver_ad_performance.py -- doctordoctor命令源码 cmd_doctor()会输出两部分信息env三个环境变量各自的布尔存在状态true/falsereachable对 Base URL 发起一次探测请求的结果。只要收到任意 HTTP 响应包括错误码即视为网络可达reachable: true只有URLErrorDNS 失败、连接超时等才判定为reachable: false。若结果为reachable: false说明当前环境出网受限应在本地如 Claude Code / Cursor CLI重新执行。第二步结构查询拿到 ID 才能查绩效# 列出全部广告系列 npx -y nomadamas/k-skill0 exec naver-ad-performance scripts/naver_ad_performance.py -- campaigns # 按广告系列 ID 列出其下的广告组 npx -y nomadamas/k-skill0 exec naver-ad-performance scripts/naver_ad_performance.py -- adgroups --campaign nccCampaignId # 按广告组 ID 列出其下的关键词 npx -y nomadamas/k-skill0 exec naver-ad-performance scripts/naver_ad_performance.py -- keywords --adgroup nccAdgroupId对应源码为 cmd_campaigns()、cmd_adgroups() 与 cmd_keywords()。adgroups与keywords分别要求必填的--campaign与--adgroup参数用于逐级下钻返回的 ID 将成为后续stats查询的--ids参数。第三步周期绩效查询核心功能# 按区间查询多个对象系列/组/关键词 ID 可混用逗号分隔 npx -y nomadamas/k-skill0 exec naver-ad-performance scripts/naver_ad_performance.py -- stats \ --ids id1,id2 --since 2026-06-01 --until 2026-06-30 # 按日细分查看每日趋势 npx -y nomadamas/k-skill0 exec naver-ad-performance scripts/naver_ad_performance.py -- stats \ --ids id --since 2026-06-01 --until 2026-06-30 --by day关键参数说明源码 cmd_stats()--ids必填广告系列/广告组/关键词 ID用逗号分隔可以混编不同类型--since/--until日期区间格式YYYY-MM-DD。二者必须成对出现只给其中一个会报错并提示--since and --until must be given together两者都省略时使用 Naver 默认时间范围最近查询--by细分维度当前仅支持day按日。参数传递时映射为请求中的breakdown字段。请求参数内部会以 JSON 序列化后提交ids、fields固定为STATS_FIELDS定义的 7 个字段以及可选的timeRange对象与breakdown见 STATS_FIELDS。第四步关键词工具npx -y nomadamas/k-skill0 exec naver-ad-performance scripts/naver_ad_performance.py -- keywordtool --keywords 제주여행,게스트하우스keywordtool命令源码 cmd_keywordtool()以逗号分隔的关键词为 hint请求/keywordstool端点并附带showDetail1返回关联关键词、月度搜索量与竞争度数据适合投放前的选词与扩词分析。返回字段与响应格式stats 绩效响应技能会对每个统计行做两件事派生缺失指标与附加韩文标签。以文档给出的响应示例为基础[ { impCnt: 12034, clkCnt: 452, salesAmt: 305000, ctr: 3.76, cpc: 674.78, avgRnk: 2.1, ccnt: 8, labels: { impCnt: 노출수, clkCnt: 클릭수, salesAmt: 광고비, ctr: CTR, cpc: CPC, avgRnk: 평균노출순위, ccnt: 전환수 } } ]各字段语义与取值逻辑如下with_derived_stats() 与 STATS_LABELS字段含义备注impCnt曝光数原始字段clkCnt点击数原始字段salesAmt广告费原始字段ctr点击率%API 未返回时由clkCnt / impCnt * 100计算保留两位小数曝光为 0 时为 0cpc单次点击成本API 未返回时由salesAmt / clkCnt计算点击为 0 时为 0avgRnk平均曝光排名原始字段ccnt转化数原始字段labels对象为每个字段附上韩文说明方便 Agent 或人工直接阅读理解。派生逻辑有专门的测试覆盖测试 test_with_derived_stats_computes_ctr_and_cpc_when_absent 验证了 CTR5.0、CPC500.0 的正确性test_with_derived_stats_avoids_division_by_zero 则保证全零数据下不会触发除零异常而是返回 0。keywordtool 关键词工具响应响应行包含relKeyword关联关键词、monthlyPcQcCnt/monthlyMobileQcCnt月度 PC / 移动搜索量、compIdx竞争程度等字段同样会附加韩文标签。标签映射表见源码 KEYWORDTOOL_LABELS其中包括月度平均 PC / 移动点击量monthlyAvePcClkCnt、monthlyAveMobileClkCnt。失败模式与排查速查表技能把错误归纳为两类异常凭证缺失抛CredentialErrorHTTP 或网络错误抛ApiError源码 naver_ad_performance.py。main()中的错误映射逻辑见 main()退出码约定为凭证问题返回1API 错误返回2。常见故障一览症状原因与处理missing required env var(s): ...环境变量未设置。错误信息会精确列出缺失的变量名按名补齐即可不会绕过错失直接继续HTTP 401签名失败——检查 API Key / Secret 是否配错或系统时钟是否准确时间戳偏差会直接导致签名不通过HTTP 403该customer_id对目标数据无查询权限检查账户权限范围HTTP 404campaign / adgroup 的 ID 写错回到结构查询步骤重新核对 IDHTTP 429调用频率超限稍后重试限流退避egress unreachable云沙箱等环境的对外网络被阻断需切回本地执行doctor的reachable: false是此问题的前置信号值得一提的是test_main_maps_api_error_status_to_exit_code_two 与 test_main_reports_missing_credentials_without_network_call 验证了退出码与错误映射行为且凭证缺失时不会发起任何网络请求。只读边界与安全设计这是该技能最重要的设计原则。允许的调用严格限定在以下 GET 端点/ncc/campaigns、/ncc/adgroups、/ncc/keywords、/stats、/keywordstool。而有意未实现的写操作包括出价变更、广告系列/广告组/关键词的增删改、预算变更、投放状态如暂停切换等。这一隔离的动机在源码注释naver_ad_performance.py与 instruction.md 中均有明确说明把会真实花钱的写操作与查询用安全边界分开防止代理误操作造成预算损失。测试 test_command_functions_only_call_get_requests 对三个结构查询命令做了断言——它们调用request()时方法一律为GET从机制上锁死了只读约束。若未来确需写能力应拆分为独立的技能或独立的审批流程。此外还有两个范围提醒其一Naver 博客/新闻/购物搜索结果查询不在本技能内应使用naver-blog-research、naver-news-search、naver-shopping-search等对应技能其二大规模周期报表TSV 异步生成/stat-reports不属于当前 v1 版本范围。技能附带的法律声明见 references/DISCLAIMER.md使用前应阅读本技能与 Naver 及其广告产品无官方关联商标与服务名称仅用于功能描述自动化查询应限于个人、非组织用途不得用于批量爬取、绕过访问控制或干扰第三方业务。小结naver-ad-performance以约 240 行标准库 Python 完整封装了 Naver 搜索广告的查询能力doctor负责环境自检campaigns/adgroups/keywords完成结构下钻stats支持多对象、多日期、按日细分的绩效拉取keywordtool提供选词数据签名采用timestamp.method.path消息体的 HMAC-SHA256 base64 方案缺失指标由本地派生补齐每个字段附带韩文标签便于 Agent 消费。加上刻意设计的只读边界与完善的错误映射它是一套小而完备、可直接复用的广告绩效查询方案。若要直接查看技能源码与测试可进一步阅读 naver_ad_performance.py、instruction.md 与 test_naver_ad_performance.py。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考