# @guardian/google-admanager-api 中文文档

规范地址：https://npmcn.com/package/%40guardian/google-admanager-api/

版本：8\.0\.2
npm 元数据更新时间：2026-10-09T10:15:06.173Z
中文译文更新时间：2026-11-17T03:54:59.925Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40guardian/google-admanager-api
原文对照：https://npmcn.com/package/%40guardian/google-admanager-api/?lang=original
项目主页：https://github.com/guardian/google-admanager-api#readme
源码仓库：https://github.com/guardian/google-admanager-api

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

- 包体积（解压后）：2.1 MB，1194 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2024-08-20T11:23:28.914Z
- 最新版本发布：2026-10-09T10:15:05.582Z
- 近 30 天下载量：6967（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：88（近 12 个月 24 个）

## 中文简介

用于节点Js的 Google 代理管理器 API 客户端库

## 安装

```sh
npm install @guardian/google-admanager-api
```

也可以使用：`pnpm add @guardian/google-admanager-api`、`yarn add @guardian/google-admanager-api`、`bun add @guardian/google-admanager-api`

## README

[![Ad Manager Logo](https://developers.google.com/ads/images/logo_admanager_192px.svg)](https://developers.google.com/ad-manager/api/start)

[Google 代理管理器 API](https://developers.google.com/ad-manager/api/start) 节点Js的客户端库.

[![NPM Version](https://img.shields.io/npm/v/@guardian/google-admanager-api.svg)](https://www.npmjs.com/~guardian) [![Package License](https://img.shields.io/npm/l/@guardian/google-admanager-api.svg)](https://www.npmjs.com/~guardian) [![NPM Downloads](https://img.shields.io/npm/dm/@guardian/google-admanager-api.svg)](https://www.npmjs.com/~guardian)

## 说明

从 [https://github.com/Niurmiguel/google-admanager-api 页面存档备份,存于互联网档案馆](https://github.com/Niurmiguel/google-admanager-api) 由于原始软件包没有保留.

开发者可以使用Google Ad Manager API来构建管理库存的应用程序,创建订单,拉取报告等.

### 安装库

```bash
$ npm install @guardian/google-admanager-api
$ yarn add @guardian/google-admanager-api
$ pnpm add @guardian/google-admanager-api
```

### 概览

#### 认证

所有Google Ad Manager API的调用都必须通过 OAuth2 的开放标准授权,允许用户对第三方应用程序授予权限,因此应用程序可以代表用户与网络服务互动. OAuth2 允许您的 Ad Manager API 客户端应用程序访问用户的 Ad Manager 账户,而无需处理或存储用户的用户名或密码.

##### 生成服务账户证书

```typescript

const credential = new GoogleSACredential({
    type: "service_account",
    project_id: "...",
    private_key_id: "...",
    private_key: "...",
    client_email: "...",
    client_id: "...",
    auth_uri: "...",
    token_uri: "...",
    ...
});

//or

const credential = new GoogleSAFileCredential('./credentials.json');

```

##### 生成用户账户证书

代表真实用户使用API比使用服务账户要复杂一些. 用户必须允许您访问他们的 Ad Manager 账户 。 这是通过将用户重定向到Google的OAuth2同意屏幕来实现的,将要求他们允许您访问他们的Ad管理器账户.

有一个 [实例](https://npmcn.com/examples/authentication/refresh-token.ts) 如何在示例文件夹中生成用户账户证书.

它使用 [刷新符号生成示例](https://npmcn.com/examples/authentication/generate-refresh-token.ts) 生成刷新符号.

还有一个选择是使用 [访问令牌](https://npmcn.com/examples/authentication/access-token.ts) 直接说 由于访问符是短暂的,你需要自己刷新.

##### 使用客户端库

```typescript

const adManagerClient = new AdManagerClient('networkCode',credential,'applicationName');

const orderService = await adManagerClient.getService("OrderService");
const statement = new StatementBuilder().limit(10);
const orderPage = await orderService.getOrdersByStatement(statement.toStatement())

/**
 * {
 *  results: [],
 *  totalResultSetSize: 0,
 *  startIndex: 0
 * }
 * /
```

##### 选项

<table><tbody><tr><td><code><b>networkCode</b></code></td><td><code>Number</code></td><td>正在处理的网络的网络代码(<b>所需经费</b>) (中文(简体) ).</td></tr><tr><td><code><b>credential</b></code></td><td><code>SACredential</code></td><td>OAuth2 证书<b>所需经费</b>) (中文(简体) ).</td></tr><tr><td><code><b>applicationName</b></code></td><td><code>String</code></td><td>一个任意的字符串名称来识别您的应用程序 。 这将在Google的日志文件中显示. 例如:"我的编目应用"或"App 1" (中文(简体) )<b>选项</b>) (中文(简体) ).</td></tr><tr><td><code><b>apiVersion</b></code></td><td><code>String</code></td><td>Ad Mananger API 版本,如果您想要定义一个与默认版本不同的版本,即 v202605 ()<b>选项</b>) (中文(简体) ).</td></tr></tbody></table>

### 验证

使用 [超级结构](https://docs.superstructjs.org/) 用于类型验证,从而可用于分析我们从不同"守护者"项目中的API获取的行项目数据.

每个类型都有自己的Struct,应该在与类型相同的文件中找到,然后用于 [项目. struct.ts](https://github.com/guardian/google-admanager-api/blob/main/lib/client/services/lineItem/lineItem.struct.ts)。 。 。 .

在早期进行类型安全检查会减少我们以后可能遇到的bug,没有比这个寄存器更好的地方可以添加.

### 调试

通过设置启用请求和响应记录 `logRequests` 和(或) `logResponses` 改为 `true` 在服务对象上.

```typescript
const orderService = await adManagerClient.getService("OrderService");
orderService.logRequests = true;
orderService.logResponses = true;
```

### 已知问题/问题

#### SOAP 要求对象属性按正确的顺序排列

使用此库发送对象的属性需要按正确的顺序排列(与类型定义的顺序相同),或者您可能遇到 `Unmarshalling Error` 反应.

例如,一个 [线性项目](https://npmcn.com/package/%40guardian/google-admanager-api/lib/client/common/types/lineItemSummary.type.ts) 页:1 `orderName` 必须是在 `startDateTime`。 。 。 .

```ts
// will not work
lineItemService.createLineitem({
  priority: 12,
  orderId: 123,
  ...
})

// must be
lineItemService.createLineitem({
  orderId: 123,
  priority: 12,
  ...
})
```

#### 一些对象需要额外的属性

在某些情况下,如果接受多种形状的物体,则需要在一个特殊的情况下指定该类型 `attributes` 属性.

例如,对于自定义目标,对象需要指定其类型是否属于 `CustomCriteriaSet` 或者说 `CustomTargeting` 像这样:

```ts
const customTargeting: CustomCriteriaSet = {
  attributes: {
    "xsi:type": "CustomCriteriaSet",
  },
  logicalOperator: LogicalOperator.OR,
  children: [{
    attributes: {
      "xsi:type": "CustomCriteriaSet",
    },
    logicalOperator: LogicalOperator.AND,
    children: [{
      attributes: {
        "xsi:type": "CustomCriteria",
      },
      keyId: 123,
      valueIds: [123],
      operator: ComparisonOperator.IS,
    }],
  }],
};

lineItemService.createLineitem({
  ...
  targeting: {
    customTargeting
  }
  ...
})
```

它还适用于技术瞄准, [因为有很多类型的技术](https://github.com/guardian/google-admanager-api/blob/main/lib/client/common/types/targeting.type.ts#L294)

```ts
type Browser = {
  attributes: {
    "xsi:type": "Browser";
  };
  id: number;
  name: string;
  majorVersion: string;
  minorVersion: string;
};
```

## 常见问题

### @guardian/google-admanager-api 是什么？

用于节点Js的 Google 代理管理器 API 客户端库

### 如何安装 @guardian/google-admanager-api？

在项目目录运行 npm install @guardian/google-admanager-api，或使用 pnpm add / yarn add / bun add。

### @guardian/google-admanager-api 支持 TypeScript 吗？

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

### @guardian/google-admanager-api 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @guardian/google-admanager-api 可以商用吗？

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

### @guardian/google-admanager-api 的下载量有多少？

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

### @guardian/google-admanager-api 还在维护吗？

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

