# @apigrate/autotask-restapi 中文文档

规范地址：https://npmcn.com/package/%40apigrate/autotask-restapi/

版本：2\.0\.1
npm 元数据更新时间：2025-01-07T16:26:40.618Z
中文译文更新时间：2026-11-06T10:05:35.929Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：67.1 kB，8 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- 首次发布：2020-06-18T16:32:36.336Z
- 最新版本发布：2025-01-07T16:26:40.396Z
- 近 30 天下载量：10650（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 0 个）

## 中文简介

用于自动任务REST API的节点JS库.

## 安装

```sh
npm install @apigrate/autotask-restapi
```

也可以使用：`pnpm add @apigrate/autotask-restapi`、`yarn add @apigrate/autotask-restapi`、`bun add @apigrate/autotask-restapi`

## README

# 自动任务 REST API 节点JS 连接器

# v2 释放注释

## 中断更改 :

1.  代码库现在使用本地取取并需要节点 > 18.0.0. (对 `isomorphic-fetch`. ) (中文(简体) )
2.  删除了 api () 方法 。 所有 API 实体引用现在都可以直接在 AutotaskRestApi 实例中获取 .
3.  API 呼叫自动引用 `zoneInformation` 需要时API. 无需初始化.

此连接器简化了与 [自动任务 PSA REST API](https://ww3.autotask.net/help/DeveloperHelp/Content/AdminSetup/2ExtensionsIntegrations/APIs/REST/REST_API_Home.htm) 用于开发者使用节点JS.

> 请确保您使用 LTS 的节点JS 版本, 或至少支持 ES6 承诺的版本 .

```bash
npm install @apigrate/autotask-restapi --save
```

## 连接到自动任务

```javascript
const {AutotaskRestApi} = require('@apigrate/autotask-restapi');

const autotask = new AutotaskRestApi(
  process.env.AUTOTASK_USER, // make sure it's an API User
  process.env.AUTOTASK_SECRET, 
  process.env.AUTOTASK_INTEGRATION_CODE 
);
```

> Autotask REST API 有分布在世界各地的终点("zones"). 连接器 **在第一次 API 呼叫时自动确定正确的终点**。不需要单独获取区域信息.

```javascript

let company = await autotask.Companies.get(0);//Get the root company

```

## 每个实体可采用的方法

以下各节列出了连接器上每个可用实体的方法.

> 并非所有方法都可能适用于一个实体。 例如,大多数实体不支持 **删除**;因此,如果在不适当的上下文中试图使用某种方法,则预期会出现错误.

### 计数

数实体. 使用自动任务 **查询过滤器语法** 以提供计算标准.

```javascript
// Count companies with a CompanyName beginning with "B"
result = await autotask.Companies.count({
  filter:[
    {
        "op": "beginsWith",
        "field": "CompanyName",
        "value": "B"
    }
  ]
});
// result = {queryCount: 7}

// Count all the contacts in Autotask
result = await autotask.Contacts.count({
  filter:[
    {
        "op": "gte",
        "field": "Id",
        "value": 0
    }
  ]
});
// result = {queryCount: 1209}
```

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/API_Calls/REST_Basic_Query_Calls.htm)

### 起来

由ID获得单一实体.

```javascript
let product = await autotask.Products.get(232486923);
// product = { item: { id: 232486923, ...product object properties... } }
```

> 当你试图通过ID获得一个实体 **不存在**,此连接器自动吞入自动任务 REST API 返回的 HTTP-404 并返回 `{item: null}`。这是一个有意的决定,目的是提高代码的可读性.

> ,使用 `get` 方法不支持。 使用 `query` 方法代替.

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/API_Calls/REST_Basic_Query_Calls.htm)

> 特例:要检索附件基数64编码数据,必须使用附件特定亲子GET请求. 用于: “ 配置项目选项” 、 “ 配置项目选项” 、 “ 机会选项” 、 “ 任务选项” 、 “ 任务选项” 、 “ Ticketattachments ” 、 “ Ticket Noteattachments ” 、 “ Time Entry Atttachments ” , 您必须使用以下选项 `get` 语法 :

通过 id 获取实体附件数据

```javascript
// TicketID 129873
// AttachmentID 232486923
let ticketAttachment = await autotask.TicketAttachments.get(129873, 232486923);

// ticketAttachment = { items: { id: 232486923, ..., data: "iVBORw0KGgoAAAANSUhEUgAAAV8AAAC (...the rest of the base64 ecoded data)..." } }
```

### 查询

查询匹配过滤表达式的实体.

```javascript
//Find a company by name
let result = await autotask.Companies.query({
  filter:[
    {
        "op": "eq",
        "field": "CompanyName",
        "value": "Sirius Cybernetics Corporation "
    }
  ]
});
```

查询结果如下(例如显示公司从上述查询中返回)

```json
{
  "items": [
    {
      "id": 29683616,
      "additionalAddressInformation": "",
      "address1": null,
      "address2": null,
      "alternatePhone1": "",
      ...
      "surveyCompanyRating": null,
      "taxID": "",
      "taxRegionID": null,
      "territoryID": null,
      "webAddress": null,
      "userDefinedFields": []
    }
  ],
  "pageDetails": {
    "count": 1,
    "requestCount": 500,
    "prevPageUrl": null,
    "nextPageUrl": null
  }
}
```

#### 在查询中返回限制字段 .

```javascript
//Find a company by name
let result = await autotask.Companies.query({
  filter:[
    {
        "op": "eq",
        "field": "CompanyName",
        "value": "Sirius Cybernetics Corporation "
    }
  ],
  includeFields:[
    "Id",
    "companyName",
    "city",
    "state"
  ]
});
```

运行上述查询会得到回复 :

```json
{
  "items": [
    {
      "id": 29683616,
      "city": "",
      "companyName": "Sirius Cybernetics Corporation",
      "state": "",
      "userDefinedFields": []
    }
  ],
  "pageDetails": {
    "count": 1,
    "requestCount": 500,
    "prevPageUrl": null,
    "nextPageUrl": null
  }
}
```

> 注意: 当使用创建过滤器并指定字段包含条件时,字段名称不具有大小写敏感性.

#### 查询用户定义的字段

可以通过包含一个 `"udf": true` 到过滤条件中的 UDF 字段表达式。 在下面的例子中,存在一个公司级UDF,名为"雇员人数". 我们可以询问哪些公司有超过0名这样的员工:

```javascript
result = await autotask.Companies.query({
  filter:[
    {
        "op": "gt",
        "field": "Number of Employees",
        "value": 0,
        "udf": true
    }
  ]
});
```

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/API_Calls/REST_Advanced_Query_Features.htm)

### 创建

创建实体.

以下创建 **企业** 使用 **公司** api. (英语).

```javascript
 let myCompany = {
      CompanyName: "Sirius Cybernetics Corporation",
      CompanyType: 3,
      Phone: '8005551212',
      OwnerResourceID: 29683995
    };;
result = await autotask.Companies.create(myCompany);
```

产生 `result`数字 :

```json
{
  "itemId": 29683664
}
```

> 请注意,自动任务REST API中的一些实体是其他实体的儿童实体。 这不会影响你 **查询或检索**,但它的确要求您在使用时提供母实体 id `create()`, (中文(简体) ), `update()`, (中文(简体) ), `replace()`,或 `delete()` 方法。 。 .

以说明 **儿童记录** 关系,以下示例将创建一个 **待办** (单位:千美元) **企业** 使用 **公司待办事宜** api. (英语).

```javascript
 let myToDo = {
  ActionType: 3,
  AssignedToResourceID: 29683995,
  CompanyID: 0, 
  ActivityDescription: "Learn more about the Autotask REST API",
  StartDateTime: '2020-06-15',
  EndDateTime: '2020-06-16',
};
result = await autotask.CompanyToDos.create(0, myToDo);
```

注意使用母体 id(company id = 0)作为第一个参数 `create` 方法。 父 id 要求为方法的第一个参数. 它产生 `result`数字 :

```json
{
  "itemId": 29684378
}
```

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/API_Calls/REST_Creating_Resources.htm)

### 更新

更新一个实体。 此更新 **只指定字段**,在其中留下其他字段不变.

以下实例更新a **企业** 电话号码.

```javascript

let updateResult = await autotask.Company.update({"id":45701237, phone: "1112223344"});

```

如上文创建()文件所提及, **儿童记录关系** 在引用子实体的更新时,需要略微更改语法. 下面是另一个例子: **儿童记录关系**,使用联系人实体。 由于联系人是公司子女,我们还必须提供公司ID 在更新前联系.

```javascript
// Here we are using the autotask.Contacts handle. Queries don't require knowledge of parent-child structure.
let queryResult = await autotask.Contacts.query({filter:[{field:'firstName', op:FilterOperators.eq, value:'Zaphod'}]});

let companyID = queryResult.items[0].companyID;

// However, here we are using the autotask.CompanyContacts handle because of the structure required by the Autotask REST API. The parent entity is provided as the first argument of the update.
let updateResult = await autotask.CompanyContacts.update(companyID, {"id":30684047, middleName: "Hortensius"});
```

> 请注意,自动任务REST API中的一些实体是其他实体的儿童实体。 这不影响您如何查询或检索它们,但它确实需要您在使用时提供母实体 ID `create()`, (中文(简体) ), `update()`, (中文(简体) ), `replace()`,或 `delete()` 方法。 。 .

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/API_Calls/REST_Updating_Data_PATCH.htm)

### 替换

替换一个实体。 此替换 **整个实体**,去除其先前的内容(只读字段除外)并取而代之的是您提供的数据.

> 请注意,自动任务REST API中的一些实体是其他实体的儿童实体。 这不影响您如何查询或检索它们,但它确实需要您在使用时提供母实体 ID `create()`, (中文(简体) ), `update()`, (中文(简体) ), `replace()`,或 `delete()` 方法。 。 .

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/API_Calls/REST_Updating_Data_PUT.htm)

### 删除

以 ID 删除一个实体.

> 请注意,自动任务REST API中的一些实体是其他实体的儿童实体。 这不影响您如何查询或检索它们,但它确实需要您在使用时提供母实体 ID `create()`, (中文(简体) ), `update()`, (中文(简体) ), `replace()`,或 `delete()` 方法。 。 .

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/API_Calls/REST_Delete_Operation.htm)

### 资讯

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/API_Calls/REST_EntityInformationCall.htm)

### 字段信息

获取特定实体域的元数据 。 这包括数据类型的信息;是否需要字段,只读等;以及应当使用的任何有效值. [相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/API_Calls/REST_EntityInformationCall.htm)

```javascript
result = await autotask.AccountToDo.fieldInfo();
```

这将产生一个 `result`数字 :

```json
{
  "fields": [
    {
      "name": "ActionType",
      "dataType": "integer",
      "length": 0,
      "isRequired": true,
      "isReadOnly": false,
      "isQueryable": true,
      "isReference": false,
      "referenceEntityType": "",
      "isPickList": true,
      "picklistValues": [
        {
          "value": "0",
          "label": "Opportunity Update",
          "isDefaultValue": false,
          "sortOrder": 0,
          "parentValue": "",
          "isActive": true,
          "isSystem": true
        },
        {
          "value": "1",
          "label": "Phone Call",
          "isDefaultValue": false,
          "sortOrder": 0,
          "parentValue": "",
          "isActive": true,
          "isSystem": true
        },
        ...
      ],
      "picklistParentValueField": "",
      "isSupportedWebhookField": false
    },
    {
      "name": "ActivityDescription",
      "dataType": "string",
      "length": 32000,
      "isRequired": false,
      "isReadOnly": false,
      "isQueryable": true,
      "isReference": false,
      "referenceEntityType": "",
      "isPickList": false,
      "picklistValues": null,
      "picklistParentValueField": "",
      "isSupportedWebhookField": false
    },
    ...
    
  ]
}
```

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/API_Calls/REST_EntityInformationCall.htm)

### udfInfo 数据

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/Entities/UserdefinedFieldsUDFs.htm)

### 特殊情况

#### 模块

模块实体允许您收集自动任务PSA中模块活动状态的信息. 只能问这个问题。 使用空或空 `.get()` 或者说 `.query()` 获得模块列表的方法.

示例

```javascript
result = await autotask.Modules.get();
```

结果 :

```json
{
  "modules": [
    {
      "key": 24,
      "value": true
    },
    {
      "key": 36,
      "value": true
    },
    {
      "key": 65,
      "value": true
    },
    ...
}

```

[相关的自动任务文档](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/Entities/ModulesEntity.htm)

## 可用实体

以下是由连接器支持的所有自动任务实体列表 :

-   动作类型
-   额外发票
-   任用
-   附件信息
-   项目负责人
-   计费码
-   计费 项目
-   计费 项目核准级别
-   更改命令
-   更改请求链接
-   明细列表
-   分类
-   客户端端用户
-   共同管理协会
-   公司
-   公司Webhooks
-   配置项目
-   配置项目类别
-   配置项目类型
-   联系人
-   联系人组
-   联系人Webhooks
-   合同
-   合同排除
-   国家
-   货币
-   部门
-   支出
-   支出报告
-   假日设置
-   内部定位
-   内部定位 与商务之旅
-   库存项目
-   库存
-   库存转让
-   发票
-   发票牌
-   模块
-   通知历史
-   机会
-   组织一级1
-   组织一级2
-   组织一级协会
-   付款期限
-   价格列表元件编码
-   价格清单产品
-   价格清单
-   价格列表
-   价格列表服务
-   价格列表服务站
-   价格列表工作模式修改器
-   产品
-   项目
-   采购核准书
-   采购订单
-   引号
-   引语
-   引用模板
-   资源
-   资源记录
-   作用
-   服务
-   服务班
-   服务呼叫
-   运输方式
-   技能
-   订阅
-   调查
-   调查结果
-   税收
-   税务类别
-   税区
-   阈值信息
-   车票
-   车票类别
-   车票历史
-   时间输入
-   用户定义字段定义
-   网络事件错误日志
-   工作类型修改器
-   区信息

REST API在一些自动任务实体中引入了亲子关系. 连接器使用简名来使与实体的合作更加直观. 下列儿童实体也得到连接者的支持:

-   明细表 明细表 明细表 明细表 明细表 明细表
-   公司 − 公司/公司
-   公司/附属公司
-   公司联系-公司/联系
-   公司/办事处
-   公司说明 公司/说明
-   公司/公司
-   公司/小组
-   公司-公司/公司
-   公司Webhook ExcledResources → 公司Webhooks/ExcledResources 互联网档案馆的存檔,存档日期2013-12-22
-   公司Webhook Fields → 公司Webhooks/ Fields
-   公司WebhookUdf Felds 公司Webhoosk/Udf Felds
-   配置项目选项 − 配置 项目/附件
-   组合项目/组合产品协会
-   配置项目类Udf协会-配置项目类/Udf协会
-   配置项目说明 — 配置项目/说明
-   配置项目说明-配置项目说明/附件
-   联系比林产品协会 联系/比林产品协会
-   联系组联系人 – 联系组/联系人
-   联系人Webhook ExcledResources – 联系人Webhooks/ExcledResources 互联网档案馆的存檔,存档日期2013-12-02
-   联系人Webhook 字段 – 联系人Webhooks/ 字段
-   联系人WebhookUdf 字段 – 联系人Webhooks/Udf 字段
-   合同订票规则-合同/订票规则
-   Contracts Blocks → Contracts/ Blocks 合同/分包
-   ContractBlockHourFactors → Contract/BlockHourFactors (合同/BlockHourFactors) 合同 合同/BlockHourFactors 合同 合同
-   合同负责人 + 合同/负责人
-   合同/排出合同
-   合同排除权 合同/排出权
-   合同排除套件 → 合同排除套件/已排除套件
-   排除合同 排除合同 排除合同 排除合同 排除合同
-   合同/石碑
-   合同说明-合同/说明
-   合同 − 合同/合同
-   合同保留人 合同/保留人
-   合同费用 − 合同费用 / 费用
-   合同/服务
-   合同/服务调整
-   合同/服务车
-   合同/服务调整
-   合同/服务股
-   合同/服务单位
-   合同/合同
-   支出项目-支出/项目
-   假日-假日/假日
-   库存项目序号 • 库存项目/序号
-   机会 附件 机会/安排
-   组织资源 组织一级协会/资源
-   项目/阶段
-   产品说明-产品/说明
-   产品-产品/轮胎
-   产品版本 − 产品/版本
-   项目-项目/附件
-   项目负责人 + 项目/负责人
-   项目说明-项目/说明
-   采购订单项目-采购订单/项目
-   采购订单项目收 —— 采购订单项目收
-   引文使用过时参数coauthors (帮助)
-   资源-资源/资源
-   资源-资源/资源
-   资源服务-资源/服务
-   资源技能 资源/技能
-   销售命令-机会/销售命令
-   服务班/服务班
-   服务呼叫任务 — 服务呼叫/任务
-   服务呼叫任务资源-服务呼叫任务/资源
-   服务电话信箱 — 服务电话/信箱
-   服务呼叫数据库资源 — 服务呼叫数据库/资源
-   服务级协议成果 服务级协议/成果
-   订阅费 + 订阅费/订阅费
-   任务-项目/任务
-   任务安排 ~ 任务/任务安排
-   任务说明-任务/说明
-   任务说明 • 任务说明/附件
-   任务前继者 – 任务/前继者
-   任务第二资源-任务/次要资源
-   车票附加配置项目-车票/附加配置项目
-   车票附加联系 ^ 车票/附加联系
-   车票-车票/车票
-   门票类别 外地故障 —— 门票类别/外地故障
-   车票换乘请求核准 ^ 车票/换乘请求核准
-   售票员 + 售票员/主管
-   出票检查列表项目 — 出票/ 出票检查列表项目
-   车票检查列表 车票/车票检查列表
-   车票 – 车票/车票
-   出票注解-出票注解/出票注解
-   车票 – 车票/车票
-   票务第二资源-票务/第二资源
-   时间输入 → 时间输入 / 附加
-   用户定义的域/列表项目

## 处理错误

REST API HTTP出错被包裹在一个自动任务ApiError类中,可用于获取关于从自动任务返回出错的进一步信息.

例如:

```javascript
try{
  let myCompany = {
    CompanyName: undefined, //<-- it is required!
    CompanyType: 3,
    Phone: '8005551212',
    OwnerResourceID: 29683995
  };
  let result = await autotask.Companies.create(myCompany);

} catch ( err ){
  if( err instance of AutotaskApiError ){
    // Custom handling is possible for Autotask REST API errors.
    console.error(`Error message: ${ err.message }\nHTTP status: ${ err.status }\nError Details: ${ JSON.stringify(err.details) }`)
  }
}
```

请注意, 在某些情况下, 自动任务 REST API HTTP 错误处理可能不会以您预期的方式进行 。 例如:

无效的 API 用户名将会导致 HTTP 500 错误返回 :

```json
{"errors":["Zone information could not be determined"]}
```

,而不是 HTTP 401 错误.

无效的 API 集成键将导致 HTTP 500 出错返回 :

```json
{"errors":["IntegrationCode is invalid."]}
```

,而不是 HTTP 401 错误.

## 调试

调试支持通过 调试 图书馆。 支持两个级别的调试:

-   **调试** 包含 `autotask:restapi` 在你身边 `DEBUG` 环境变量
-   **动词** 包含 `autotask:restapi:verbose` 或简单 `autotask:restapi*` 在你身边 `DEBUG` 环境变量.

# 如果你喜欢这个...

### [找我们](https://www.apigrate.com/) 用于API集成咨询以及全库应用开发.

![Apigrate](https://www.apigrate.com/content/images/2023/12/HORIZONTAL-PRIMARY-TRANSPARENT.png)

## 常见问题

### @apigrate/autotask-restapi 是什么？

用于自动任务REST API的节点JS库\.

### 如何安装 @apigrate/autotask-restapi？

在项目目录运行 npm install @apigrate/autotask-restapi，或使用 pnpm add / yarn add / bun add。

### @apigrate/autotask-restapi 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/apigrate\_\_autotask-restapi 是否存在。

### @apigrate/autotask-restapi 支持 ESM 还是 CommonJS？

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

### @apigrate/autotask-restapi 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @apigrate/autotask-restapi 可以商用吗？

@apigrate/autotask-restapi 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @apigrate/autotask-restapi 的下载量有多少？

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

### @apigrate/autotask-restapi 还在维护吗？

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