# @crvouga/mockingbird-service-google-ads 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-google-ads/

版本：1\.12\.0
npm 元数据更新时间：2026-11-11T02:13:42.961Z
中文译文更新时间：2026-11-11T05:46:34.083Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-google-ads
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-google-ads/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/google-ads#readme
源码仓库：https://github.com/crvouga/mockingbird

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.5 MB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-10-05T09:26:05.969Z
- 最新版本发布：2026-11-11T02:13:42.572Z
- 近 30 天下载量：3135（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

Google Ads v25和GA4模拟器:GAQL度量衡,预算突变,转换上传和分析事件/报告.

## 安装

```sh
npm install @crvouga/mockingbird-service-google-ads
```

也可以使用：`pnpm add @crvouga/mockingbird-service-google-ads`、`yarn add @crvouga/mockingbird-service-google-ads`、`bun add @crvouga/mockingbird-service-google-ads`

## README

# @crvouga/ mockingbird-service-google-ads (中文(简体) )

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

A 类 **阴道** google Ads API v25和Google Analytics 4. 便携式模拟器. 它提供了决定性的 GAQL 报告、运动预算变异、点击转换上传、计量协议活动 集合,并使用命名空间 SQLite 状态和注入时钟进行分析数据报告.

## 安装

```sh
bun add @crvouga/mockingbird-service-google-ads
```

## 使用量

```ts
import { OAuth2Client } from "google-auth-library"
import { DEFAULT_CUSTOMER, DEFAULT_TOKEN } from "@crvouga/mockingbird-service-google-ads"
import { createServer } from "@crvouga/mockingbird-service-google-ads/server"

const emulator = await createServer()

// Google publishes no Node client for the Ads API, so the application calls REST through
// google-auth-library. Only the base URL and the fixture token change.
const client = new OAuth2Client()
client.setCredentials({ access_token: DEFAULT_TOKEN })
const response = await client.request({
  url: `${emulator.url}/v25/customers/${DEFAULT_CUSTOMER}/googleAds:search`,
  method: "POST",
  data: { query: "SELECT campaign.id, campaign.name, metrics.clicks FROM campaign" },
})
console.log(response.data)

await emulator.close()
```

Ads和Analytics Data路由使用OAuth Bearer证书. 测量协议路线的使用 页:1 `measurement_id` 财务报告和审定财务报表 `api_secret` 查询参数。 导出默认值为合成并 安全测试。 配置 `tokens`客户、竞选活动、预算、转换行动、计量标准、, 和分析属性 `createRuntime` 选项,当套房需要不同的固定装置.

对于平行测试,请发送 `x-mockingbird-namespace`,使用共享 `/__admin/ns/{namespace}` 路径, 或向共享管理员API注册证书。 状态 相片 身份证 时钟, 断层,和resets被命名空间隔离.

## 支助行动

| 运行 | 路线 | 行为 |
| --- | --- | --- |
| 搜索 Google 坐标 | `POST /v25/customers/{customerId}/googleAds:search` | GAQL 选择、过滤、订购、汇总、摘要行、 固定一万行页面、 绑定到查询的两小时的页面符号和仅验证请求 |
| 搜索结构 GoogleAds | `POST /v25/customers/{customerId}/googleAds:searchStream` | 确定 JSON 批次和可选摘要行 |
| 变相Campaign预算 | `POST /v25/customers/{customerId}/campaignBudgets:mutate` | 创建、更新、去除、更新口罩、仅验证和原子或部分失败 |
| 上传 Click 转换 | `POST /v25/customers/{customerId}:uploadClickConversions` | 单击标识符、转换动作、重复检测、工作标识和部分失败 |
| 收集分析事件 | `POST /mp/collect` | 204号生产式空答复,已接受事件存档供报告 |
| 验证分析事件 | `POST /debug/mp/collect` | 不摄入的验证信件 |
| 运行分析报告 | `POST /v1beta/properties/{propertyId}:runReport` | 尺寸、度量、过滤器、定购、标记和报告滞后 |
| 批量运行分析报告 | `POST /v1beta/properties/{propertyId}:batchRunReports` | 至多5项报告要求 |

确切的要求和反应计划 [`openapi.yaml`](https://npmcn.com/package/%40crvouga/mockingbird-service-google-ads/openapi.yaml)生成 支持矩阵在 [`SUPPORT.md`](https://npmcn.com/package/%40crvouga/mockingbird-service-google-ads/SUPPORT.md)。 。 。 .

运动预算与GAQL(`FROM campaign_budget`; 上传转换和 收集的事件通过下面的检查路线读取,事件也通过以下检查路线读取 分析数据报告. REST行使用 protobuf JSON 名 (`costMicros`, (中文(简体) ), `conversionsValue`, (中文(简体) ), `conversionActionCategory`)和 int64 值为字符串; GAQL 字段名保留为蛇 case.

谷歌 失败是一个 `google.rpc.Status` 谁 `details` 拿着 `GoogleAdsFailure` 与 业务活动 `errorCode`, (中文(简体) ), `message`, (中文(简体) ), `location` (单位:千美元) `requestId` 等于 `request-id` 响应头。 无法解析的 JSON 和每一次分析数据失败都是空虚状态,没有 Ads 细节和否 `request-id` 头曰.

## 谷歌与普通假设的不同之处

这些都跟Google的文档和封存的 `googleapis` 25个原型而不是什么 与旧合同相对应的客户可能会期待.

-   **搜索页面大小已固定 .** `Search` 返回可达一万行的页并请求 套装 `pageSize` 以 `requestError: PAGE_SIZE_NOT_SUPPORTED`。通过再发送继续 相同的查询与 `pageToken`; 更改的查询是 `INVALID_PAGE_TOKEN` 和未使用的符号 两小时 `EXPIRED_PAGE_TOKEN` (单位:千美元)[向导](https://developers.google.com/google-ads/api/docs/reporting/paging), (中文(简体) ), [`SearchGoogleAdsRequest`](https://github.com/googleapis/googleapis/blob/03a91044136a014466d4293eb1fe91f2b02075d2/google/ads/googleads/v25/services/google_ads_service.proto)) (中文(简体) ). 将模拟器的页面与 `searchPageSize` 设置 请求仍然无法选择.
-   **`/mp/collect` 从未在 HTTP 上报告验证错误 .** 它回答一个空 `204` (单位:千美元) 坏的秘密,一个无法解冻的身体 或一个被拒绝的事件一样。 检查拒绝方式 `POST /debug/mp/collect`返回时 `validationMessages` 并存储什么,或与 `GET /__admin/request-metadata`,记录 `accepted`, (中文(简体) ), `rejected`, (中文(简体) ), `duplicate` 财务报告和审定财务报表 `reasons` 每个请求 (单位:千美元)[验证指南](https://developers.google.com/analytics/devguides/collection/protocol/ga4/validating-events)) (中文(简体) ).
-   **超过72小时的时间戳被推翻,没有被拒绝,** 除非请求设定 `validation_behavior: "ENFORCE_RECOMMENDATIONS"` (单位:千美元)[发送向导](https://developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events?client_type=gtag)) (中文(简体) ). 谷歌的文档没有未来时间戳的束缚,所以一分钟 `futureToleranceMs` 默认 是这个模拟者的测试政策,而不是供应商规则 `null` 来禁用它.
-   **只验证的预算突变只返回错误 .** 有效的飞行前答案 `{}` 没有 `results` 写什么 (单位:千美元)[`MutateCampaignBudgetsRequest`](https://github.com/googleapis/googleapis/blob/03a91044136a014466d4293eb1fe91f2b02075d2/google/ads/googleads/v25/services/campaign_budget_service.proto)) (中文(简体) ).
-   **变异不取一能克.** 重复警卫是Google自己的:共享预算 名称( e)`campaignBudgetError: DUPLICATE_NAME`),转换 `orderId` (单位:千美元)`ORDER_ID_ALREADY_IN_USE`),单击和转换时间(`CLICK_CONVERSION_ALREADY_EXISTS`, (中文(简体) ), 和网络 `purchase` 事件 `transaction_id` 每个用户.
-   **`developer-token` 被接受和忽略.** 被钉住的原型 标志着开发者脚趾 作为日落的错误; `login-customer-id` 仍在检查客户的经理.

## 控制和失败

特定服务控制由共享控制保护 `x-mockingbird-admin-key` 守护并活下来 除了共享健康,状态,时钟,日记,过失,重置,以及时间线终点.

| 控制权 | 目的 |
| --- | --- |
| `GET /__admin/events` | 检查存储分析事件, 最早 |
| `GET /__admin/conversions` | 检查上传的转换, 最早 |
| `GET /__admin/budgets` | 检查运动预算 |
| `GET /__admin/budget-mutations` | 检查突变的审计线索: 请求ID, `before` 财务报告和审定财务报表 `after` 每笔 |
| `GET /__admin/request-metadata` | 检查已编辑的请求元数据 |
| `POST /__admin/daily-metrics` | 种子合成日报`availableAt` 延迟一行) |
| `POST /__admin/page-tokens/expire` | 过期所有当前 GAQL 页面符号 |
| `GET /__admin/settings` | 读取 `reportingLagMs`, (中文(简体) ), `pageTokenTtlMs`, (中文(简体) ), `futureToleranceMs` 财务报告和审定财务报表 `searchPageSize` |
| `PUT /__admin/settings` | 更新这些决定性测试设置 |

| 改为: | 使用 |
| --- | --- |
| 提前报告日期 | `POST /__admin/clock {"advance": "1d"}` 或者说 `{"set": "<ISO-8601>"}`; GAQL 系统 `DURING` 范围和分析 `today`编号 :`yesterday`编号 :`NdaysAgo` 跟着它 |
| 延迟报告 | `PUT /__admin/settings {"reportingLagMs": n}` 隐藏新的事件,直到时间流逝 |
| 页面小固定 | `PUT /__admin/settings {"searchPageSize": n}` (1至10 000) |
| 添加延迟 | 页:1 `slow_response` 预设,或 `POST /__admin/faults {"latencyMs": n, "count": 1}` |
| 一个请求失败 | 页:1 `server_error` 或者说 `network_reset` 预设 |
| 喉咙 | 页:1 `quota_exhausted` 或者说 `rate_limited` 预设; `"count": n` 节流阀n请求 |
| 看什么来了 | `GET /__admin/requests` (日记)和 `GET /__admin/request-metadata` |

错误预设为 `quota_exhausted`, (中文(简体) ), `rate_limited`, (中文(简体) ), `server_error`, (中文(简体) ), `network_reset`, (中文(简体) ), `slow_response`, (中文(简体) ), `ambiguous_budget_write`, (中文(简体) ), `partial_budget_failure`,以及 `partial_conversion_failure`每次起火一次,除非 `count` 说不出来,被限制在 呼叫命名空间。 两节节奏预设答案 `429 RESOURCE_EXHAUSTED` 与 `quotaError: RESOURCE_EXHAUSTED` 或者说 `RESOURCE_TEMPORARILY_EXHAUSTED` 后退时 `details.quotaErrorDetails.retryDelay`在写东西之前.

`ambiguous_budget_write` 执行下一个预算突变后返回 `503`这样 重试逻辑可以通过不确定的结果进行测试. 只有验证的飞行前执行 无所不用其极:错在于等待下面的真正呼唤。 调试前 重放: 该 `503` 携带一个 `request-id` 页眉,以及 `GET /__admin/budget-mutations` 列出 根据该请求写入预算编号 `before` 财务报告和审定财务报表 `after`。 。 。 .

敏感事件和转换有效载荷被密封在州内;期刊和检查元数据 仅包含断言所需的字段.

## API 密码

便携式根导出 `GoogleAdsAPI`, (中文(简体) ), `createRuntime`, (中文(简体) ), `document`, (中文(简体) ), `supportedOperationIds`, (中文(简体) ), `GOOGLE_ADS_NAMESPACE`, (中文(简体) ), `GOOGLE_ADS_PRESETS`, (中文(简体) ), `DEFAULT_ADMIN_KEY`, (中文(简体) ), `DEFAULT_TOKEN`, (中文(简体) ), `DEFAULT_CUSTOMER`, (中文(简体) ), `DEFAULT_CUSTOMERS`, (中文(简体) ), `DEFAULT_BUDGETS`, (中文(简体) ), `DEFAULT_CAMPAIGNS`, (中文(简体) ), `DEFAULT_ACTIONS`, (中文(简体) ), `DEFAULT_PROPERTY`, (中文(简体) ), `DEFAULT_MEASUREMENT`, (中文(简体) ), `DEFAULT_API_SECRET`, (中文(简体) ), `createVaultKey`, (中文(简体) ), `fingerprint`, (中文(简体) ), 以及公共固定/运行时间选项类型。 节点 `./server` 进口 `createServer`, (中文(简体) ), `DEFAULT_PORT`,以及服务器类型. `mockingbird-google-ads serve` 开始一个听众.

## 核查和范围

接受测试包括GAQL精度和呼号、预算飞行前和部分书写、转换 分解、GA4事件验证和报告、OAuth范围/过期行为、加密状态、, 命名空间、重置、断层恢复和未修改 `google-auth-library` 11.1.0 HTTP 签名 路径。 运行时间测试驱动上方的每个控制 `/__admin`. 财产测试 实现对等操作,并证明确定检测到不同的运输方式.

`test/consumer.ts` 是原始服务请求中描述的原始流量的端口. 这不是请求软件的客户端,其来源不在这个寄存器中,所以没有测试 在此运行未修改的客户端 .

## 故意不模拟

模拟器执行一个有界限的子集。 它不模拟完整的 Google Ads 资源 图表,每个 GAQL 函数, GAQL 字段相容性规则在段和度量之间 分析维度或度量,真实的Google身份,生产配额分配,计费, 仪表板,归属处理,或无证后端行为. 上传的转换没有 种子 `metrics.conversions`;种子那些有日用度量的. 正常操作为本地操作, 不 联系Google; 只有明确的等同命令使用通过 `.env.local` 或 GitHub 动作秘密 .

## 常见问题

### @crvouga/mockingbird-service-google-ads 是什么？

Google Ads v25和GA4模拟器:GAQL度量衡,预算突变,转换上传和分析事件/报告\.

### 如何安装 @crvouga/mockingbird-service-google-ads？

在项目目录运行 npm install @crvouga/mockingbird-service-google-ads，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-google-ads，可以用 npx mockingbird-google-ads 直接运行。

### @crvouga/mockingbird-service-google-ads 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @crvouga/mockingbird-service-google-ads 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @crvouga/mockingbird-service-google-ads 可以商用吗？

@crvouga/mockingbird-service-google-ads 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @crvouga/mockingbird-service-google-ads 的下载量有多少？

根据 npm 官方下载统计，@crvouga/mockingbird-service-google-ads 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,135 次，日均约 105 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crvouga/mockingbird-service-google-ads 还在维护吗？

最新版本 1\.12\.0 发布于 2026/11/11（今天）；至今共发布 23 个版本，其中过去 12 个月发布了 23 个；首次发布于 2026/10/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。