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

v2 释放注释

中断更改 :

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

此连接器简化了与 自动任务 PSA REST API 用于开发者使用节点JS.

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

npm install @apigrate/autotask-restapi --save

连接到自动任务

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 呼叫时自动确定正确的终点。不需要单独获取区域信息.

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

每个实体可采用的方法

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

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

计数

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

// 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}

相关的自动任务文档

起来

由ID获得单一实体.

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

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

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

相关的自动任务文档

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

通过 id 获取实体附件数据

// 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)..." } }

查询

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

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

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

{
  "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
  }
}

在查询中返回限制字段 .

//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"
  ]
});

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

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

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

查询用户定义的字段

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

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

相关的自动任务文档

创建

创建实体.

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

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

产生 result数字 :

{
  "itemId": 29683664
}

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

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

 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数字 :

{
  "itemId": 29684378
}

相关的自动任务文档

更新

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

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

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

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

// 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() 方法。 。 .

相关的自动任务文档

替换

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

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

相关的自动任务文档

删除

以 ID 删除一个实体.

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

相关的自动任务文档

资讯

相关的自动任务文档

字段信息

获取特定实体域的元数据 。 这包括数据类型的信息;是否需要字段,只读等;以及应当使用的任何有效值. 相关的自动任务文档

result = await autotask.AccountToDo.fieldInfo();

这将产生一个 result数字 :

{
  "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
    },
    ...
    
  ]
}

相关的自动任务文档

udfInfo 数据

相关的自动任务文档

特殊情况

模块

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

示例

result = await autotask.Modules.get();

结果 :

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

相关的自动任务文档

可用实体

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

• 动作类型
• 额外发票
• 任用
• 附件信息
• 项目负责人
• 计费码
• 计费 项目
• 计费 项目核准级别
• 更改命令
• 更改请求链接
• 明细列表
• 分类
• 客户端端用户
• 共同管理协会
• 公司
• 公司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类中,可用于获取关于从自动任务返回出错的进一步信息.

例如:

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 错误返回 :

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

,而不是 HTTP 401 错误.

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

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

,而不是 HTTP 401 错误.

调试

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

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

如果你喜欢这个...

找我们 用于API集成咨询以及全库应用开发.