# @apple/apple-ads-platform 中文文档

规范地址：https://npmcn.com/package/%40apple/apple-ads-platform/

版本：1\.117\.0
npm 元数据更新时间：2026-10-13T15:04:17.940Z
中文译文更新时间：2026-11-06T11:39:16.854Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.6 MB，1599 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-08-14T16:18:17.593Z
- 最新版本发布：2026-10-13T15:04:17.492Z
- 近 30 天下载量：14176（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

用于 Apple Ads 平台 API 的 Node.js 客户端库

## 安装

```sh
npm install @apple/apple-ads-platform
```

也可以使用：`pnpm add @apple/apple-ads-platform`、`yarn add @apple/apple-ads-platform`、`bun add @apple/apple-ads-platform`

## README

# Apples 平台 API 节点

用于苹果Ads平台API的Node.js / TypeScript客户端库.

## 模型和端点文档

该图书馆是安装和使用该图书馆的主要文件。 对于 关于数据模型和API端点的信息,见 [Apple Ads 平台 API 文档](https://developer.apple.com/documentation/apple-ads-platform-api) 在苹果公司的开发商网站上找到.

## 安装

从 npm 安装此库 。 就像几乎任何软件依赖,你应该针 特定版本,仅在您明确打算时更新.

```bash
npm install @apple/apple-ads-platform
```

或者把它加进你的 `package.json` `dependencies`数字 :

```json
{
  "dependencies": {
    "@apple/apple-ads-platform": "VERSION"
  }
}
```

载有类型Script申报的图书馆船——没有单独的 `@types/...` 需要软件包.

## 开始

这个图书馆很容易创建 [`AppleAdsApi`](https://npmcn.com/package/%40apple/apple-ads-platform/src/api/apple-ads-api.ts) 实例 a 一个 [`axios`](https://axios-http.com/) HTTP客户端已准备好呼叫苹果Ads平台API. 这个 [`createAppleAdsApi`](https://npmcn.com/package/%40apple/apple-ads-platform/src/factory.ts) 工厂接受认证所需的信息 和各种可选设置。 由此产生的客户端透明地执行 OAuth 流量 .

### 客户建设

您可以以三种方式即时处理客户端, 由 `authMode` 选项对象上的字段.

#### 使用您的私钥

创建客户端的第一个方法是提供一条通往您的路径 `.pem` 私有密钥文件与 其他相关的元数据。 图书馆在施工时读过钥匙一次 每次需要新的访问令牌时都会生成新的客户端秘密.

```ts
import { createAppleAdsApi } from '@apple/apple-ads-platform';

const api = await createAppleAdsApi({
  authMode: 'key',
  clientId: '...',
  teamId: '...',
  keyId: '...',
  privateKeyPath: '/path/to/your/private/key.pem',
});
```

#### 使用自定义客户端加密工具

如果您希望以不同的方式生成客户机密(例如,生成其离线和 在运行时使用固定服务,或在签字时使用单独的服务),通过执行 [`ClientSecretProvider`](https://npmcn.com/package/%40apple/apple-ads-platform/src/auth/types.ts)。图书馆在需要客户端保密时使用它 用于获取新的访问符.

```ts
import { createAppleAdsApi, ClientSecretProvider } from '@apple/apple-ads-platform';

const clientSecretProvider: ClientSecretProvider = {
  getClientSecret: () => '...',
};

const api = await createAppleAdsApi({
  authMode: 'clientSecret',
  clientId: '...',
  clientSecretProvider,
});
```

#### 执行 OAuth 自己

我们建议让图书馆处理OAuth的流量 有具体要求的,可以 用一个 [`AccessTokenProvider`](https://npmcn.com/package/%40apple/apple-ads-platform/src/auth/types.ts)。在这种情况下,图书馆在每一个API之前都叫它 请求以附加一个访问符作为 HTTP 标题.

```ts
import { createAppleAdsApi, AccessTokenProvider } from '@apple/apple-ads-platform';

const accessTokenProvider: AccessTokenProvider = new MyAccessTokenProvider(/* ... */);

const api = await createAppleAdsApi({
  authMode: 'token',
  accessTokenProvider,
});
```

### 可选设置

下面的所有选项都有合理的默认,可能会被省略. 选项作为字段在 相同的选项对象.

#### 常见 `authMode` 数值)

| 外地 | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| `apiTimeout` | `number` (单位:百万美元) | API请求的超时 . | `5000` |
| `maxSockets` | `number` | API 连接池每个主机的最大打开套接字 . | `50` |
| `maxFreeSockets` | `number` | API 连接池中每个主机最大闲置的 keep- socket . | `10` |
| `freeSocketTimeout` | `number` (单位:百万美元) | 这么多毫秒后, Idle socket 被从 API 池中拆出 。 设定在服务器的保存- 闲置超时下, 以避免 Stale 连接出错 . | `30000` |
| `apiAxiosCustomizer` | `(instance: AxiosInstance) => void` | 创建后对主 API axios 实例应用回调,允许额外定制(代理设置,额外截取器,头等). 见 [轴](https://axios-http.com/docs/interceptors) 可能情况下的文件. | 无适用 |
| `logger` | `Logger | null` | 请求/响应日志截取器使用的 Logger 。 过 `null` 要完全禁用日志。 执行 [`Logger`](https://npmcn.com/package/%40apple/apple-ads-platform/src/auth/types.ts) 接口工程(与 `console`, (中文(简体) ), `winston`,以及 `pino` 一个小包装。 这个 `Authorization` 信头从未被记录 . | `console` |
| `requestLogLevel` | `'debug' | 'info' | 'warn' | 'error'` | 请求启动和成功响应的日志级别 。 适用于 API 和 assios 实例 . | `'info'` |
| `errorLogLevel` | `'debug' | 'info' | 'warn' | 'error'` | 请求错误的日志级别 。 适用于 API 和 assios 实例 . | `'error'` |

#### 增加额用于 `authMode: 'key'` 财务报告和审定财务报表 `authMode: 'clientSecret'`

| 外地 | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| `authTimeout` | `number` (单位:百万美元) | 给 Auth 服务器的令牌请求超时 . | `5000` |
| `authAxiosCustomizer` | `(instance: AxiosInstance) => void` | 与 `apiAxiosCustomizer` 但对于axios的例子 用于认证符号请求. | 无适用 |

#### 可选设置示例

```ts
const api = await createAppleAdsApi({
  authMode: 'key',
  clientId: '...',
  teamId: '...',
  keyId: '...',
  privateKeyPath: '/path/to/your/private/key.pem',
  apiTimeout: 10_000,
  requestLogLevel: 'debug',
});
```

## 实例

这个 `xApContext` 标出该请求适用的广告账户. 这是一个简单的字符串——按照API的要求为您所呼叫的终点构建它.

#### 查询活动

```ts
import {
  createAppleAdsApi,
  QueryRequest,
  QueryFilterOperator,
  CampaignSystemStatus,
} from '@apple/apple-ads-platform';

const api = await createAppleAdsApi({
  authMode: 'key',
  clientId: '...',
  teamId: '...',
  keyId: '...',
  privateKeyPath: '/path/to/your/private/key.pem',
});

const runningCampaignsRequest: QueryRequest = {
  filters: [
    {
      field: 'systemStatus',
      operator: QueryFilterOperator.Equals,
      value: CampaignSystemStatus.Running,
    },
  ],
};

const xApContext = '...'; // e.g. "adAccountId=12345678;" 

const response = await api.campaignsQueryPost(xApContext, runningCampaignsRequest);
```

#### 通过 ID 获取商务品牌

```ts
const api = await createAppleAdsApi({
  authMode: 'key',
  clientId: '...',
  teamId: '...',
  keyId: '...',
  privateKeyPath: '/path/to/your/private/key.pem',
});

const brandId = '...';
const xApContext = '...';

const response = await api.getBrand(xApContext, brandId);
```

#### 更新关键字标注

```ts
import { createAppleAdsApi, KeywordUpdate } from '@apple/apple-ads-platform';

const api = await createAppleAdsApi({
  authMode: 'key',
  clientId: '...',
  teamId: '...',
  keyId: '...',
  privateKeyPath: '/path/to/your/private/key.pem',
});

const keywordId = '...';
const xApContext = '...';

const keywordUpdate: KeywordUpdate = {
  bid: { amount: '1.00', currency: 'USD' },
};

const response = await api.keywordsIdPut(keywordId, xApContext, keywordUpdate);
```

## 处理错误

每个失败的请求——非-2xx响应或运输/网络故障——被转换为 [`ApiRequestError`](https://npmcn.com/package/%40apple/apple-ads-platform/src/errors.ts) 在它逃出图书馆之前 错误是平整的 可序列( 安全到 `JSON.stringify` 它只载着平板球`code`, (中文(简体) ), `status`, (中文(简体) ), `statusText`, (中文(简体) ), `method`, (中文(简体) ), `url`加服务器的应答有效载荷(`data`) (中文(简体) ). 从来没有 保留了基本的轴误差、套接字或连接池代理.

```ts
import { ApiRequestError } from '@apple/apple-ads-platform';

try {
  await api.getBrand(xApContext, brandId);
} catch (err) {
  if (err instanceof ApiRequestError) {
    console.error(err.status, err.data);
  }
  throw err;
}
```

## 保存您的身份证明

你的私人密钥和客户秘密是敏感的证明 别把它们当作纯正的文字. 把访问符也当作秘密 库中不记录任何这些值( `Authorization` 页眉在日志输出中被明确省略). 如果您选择添加任何 通过客户端的更定制,增加记录或可观察性.

## 重用客户端

在许多飞行请求中,客户可以安全地同时使用。 创建单一实例 并在整个应用程序中分享。 最大限度地扩大 内置的保持-活性连接池并最小化给 OAuth 服务器的呼叫. 如果你提供你的 拥有 `AccessTokenProvider`,货币行为取决于执行.

## 元素类型

模型定义使用 TypeScript `enum` 有字符串值的类型(参见 [`src/model`](https://npmcn.com/package/%40apple/apple-ads-platform/src/model)) 整个API模型. 随着API本身随时间演变,新的enum 值可能会出现。 因为库中不会显示未知的enum值 解序列化,一个响应可以包含一个不匹配当前任何成员的字符串 um. 与已知的馆员相比,请注意,并更新图书馆,以确保 您有匹配最新版本API的模型类型.

# 节点命令

## 测试

### `npm test`

运行完整测试套房一次并报告结果. 使用此功能进行CI或快速本地检查 .

### `npm run test:coverage`

运行完整的测试套件并生成编码封面报告 `coverage/`打开 `coverage/lcov-report/index.html` 在浏览器中显示逐行的详细视图.

## 大楼

### `npm run build`

编译类型脚本源入 `src/` 到 Java 脚本在 `dist/`,包括类型声明文件(`.d.ts`) (中文(简体) ). 这个 `prebuild` 步骤自动清理 `dist/` 先说 在发布前运行此功能 .

## 扶养管理

### `npm run update-deps`

检查所有依赖关系的最新版本并交互升级 `package.json`,然后安装更新的软件包。 电源 `npm-check-updates` (单位:千美元)`ncu`) (中文(简体) ). 运行后的审查和测试——主要版本的起伏可能包含断裂变化.

## 许可证

这个项目根据麻省理工学院的许可发布. 见 [自由主义](https://npmcn.com/package/%40apple/apple-ads-platform/LICENSE) 详细情况.

## 常见问题

### @apple/apple-ads-platform 是什么？

用于 Apple Ads 平台 API 的 Node\.js 客户端库

### 如何安装 @apple/apple-ads-platform？

在项目目录运行 npm install @apple/apple-ads-platform，或使用 pnpm add / yarn add / bun add。

### @apple/apple-ads-platform 支持 TypeScript 吗？

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

### @apple/apple-ads-platform 支持 ESM 还是 CommonJS？

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

### @apple/apple-ads-platform 可以商用吗？

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

### @apple/apple-ads-platform 的下载量有多少？

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

### @apple/apple-ads-platform 还在维护吗？

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