商业层 SDK Utils
一个 JavaScript 库, 使与它互动变得更加容易 商业层 API 使用官员 Java 脚本 SDK。 。 。 .
安装和使用
SDK v8.x (请求) ^8.0.0(中文(简体) )
Core API 是版本的, 所以 SDK v8 需要 apiVersion 当创建客户端时。 默认条目 @commercelayer/sdk 是一个捆绑的客户端, 它携带每个资源: 传递给 CommerceLayerUtils 并且所有设施都可以使用.
import { CommerceLayer } from "@commercelayer/sdk"
import CommerceLayerUtils, { executeBatch } from '@commercelayer/sdk-utils'
const cl = CommerceLayer({ organization, accessToken, apiVersion: '2026-05' })
CommerceLayerUtils(cl)
await executeBatch(batch)
利用树摇的优势,使用来自 @commercelayer/sdk/single-client 并且只通过你真正需要的资源.
import { CommerceLayer, orders, customers } from "@commercelayer/sdk/single-client"
import CommerceLayerUtils, { retrieveAll } from '@commercelayer/sdk-utils'
const cl = CommerceLayer({ organization, accessToken, apiVersion: '2026-05' })
CommerceLayerUtils(cl, [ orders, customers ])
const customerList = await retrieveAll<Customer>('customers')
资源也可以在后期被添加到CommerceLayerUtils配置.
import { CommerceLayer, orders, customers, skus } from "@commercelayer/sdk/single-client"
import CommerceLayerUtils from '@commercelayer/sdk-utils'
const cl = CommerceLayer({ organization, accessToken, apiVersion: '2026-05' })
const utilsConfig = CommerceLayerUtils(cl)
utilsConfig.addApiResources(orders, customers)
utilsConfig.addApiResource(skus)
[注] 在单一客户端的情况下,一个工具只能使用传递给的资源
CommerceLayerUtils: 调用retrieveAll('skus')不添加skus掷出Resource [skus] not available。 。 。 .
SDK v7.x (英语)
使用 @commercelayer/sdk-utils 4.x (要求数) ^7.11.0) (中文(简体) ).
职能和公用事业一览表
共同职能
清理
出口
进口
网络呼号
- 解除 Payload 的正常状态 - 剖析一个网钩有效载荷,并将其转换成适当的SDK物体
SDK 查询助手
共同职能
执行批次
此功能允许准备然后执行一些 API 调用,而无需担心当前利率限制.
for (const emailAddress of emailList) {
const task: Task = {
resourceType: "customers",
operation: "create",
resource: { email: emailAddress } as CustomerCreate,
onSuccess: { callback: sendEmail },
onFailure: { errorHandler: handleError }
}
tasks.push(task)
}
const batch: Batch = {
tasks,
options: { refreshToken: refreshAccessToken }
}
await executeBatch(batch)
在上述例子中 onSuccess 财务报告和审定财务报表 onFailure 如果执行成功或失败,则使用回调处理任务结果.
也可以从上批量步骤的结果中取出值来填充资源属性. 在下面的例子中,我们正在更新一个资源,其编号取自以前的 retrieve 或者说 create 任务 :
const task: Task = {
resourceType: "customers",
operation: "update",
prepareResource: (res: TaskResourceParam, last: TaskResourceResult): TaskResourceParam => {
return {
...res,
id: last.id,
reference: 'new-reference'
}
}
}
全部检索
此功能允许获取特定类型的所有现有资源, 执行所有必要的API请求, 遵守当前 API 费率限制 .
这个 limit 选项只能用于获取数量有限的资源.
const skus = await retrieveAll<Sku>('skus', { limit: 100 })
全部更新
此函数允许修改一组特定类型的资源,使用过滤器来识别它们.
const skuData = { reference_origin: 'legacy-system-0' }
const filters = { created_at_lt: '2023-01-01' }
const updateResult = await updateAll('skus', skuData, { filters })
删除全部
此函数允许删除一组特定类型的资源,使用过滤器来识别它们.
const filters = { created_at_lt: '2023-01-01', reference_origin_eq: 'legacy-system-0' }
const deleteResult = await deleteAll('skus', { filters })
检索页面
此功能可以获取一个特定资源子集,定义API不允许的页面属性,并使用所有标准通用过滤器. 如果页面参数与现有资源数量不相容,则会出现错误.
const skus = await retrievePage<Sku>('skus', { pageNumber: 16, pageSize: 139, sort: ['code'] })
清理
分页清除
在多项清理中分开清理,同时遵守资源的最大限度
const clp: CleanupCreate = {
resource_type: 'customers',
filters: { created_at_gt: '2020-01-01'}
}
const splitClp: CleanupCreate[] = await splitCleanup(clp)
执行清除
在多项清理中分拆清理,尊重所包括资源的最大限度,并加以执行
const clp: CleanupCreate = {
resource_type: 'customers',
filters: { created_at_gt: '2020-01-01'}
}
const execClp: CleanupResult[] = await executeCleanup(clp)
清理到批量任务
转换所生成的清理列表 splitCleanup 到函数可以执行的任务列表 executeBatch
const clps = await splitCleanup(clp)
const tasks = cleanupsToBatchTasks(clps)
出口
拆分输出
在多个出口中分割一个出口,同时遵守资源的最大限度
const exp: ExportCreate = {
resource_type: 'customers',
filters: { created_at_gt: '2020-01-01'}
}
const splitExp: ExportCreate[] = await splitExport(exp)
执行导出
在多个出口中分割一个出口,同时尊重所包含资源的最大限制,并加以执行
const exp: ExportCreate = {
resource_type: 'customers',
filters: { created_at_gt: '2020-01-01'}
}
const execExp: ExportResult[] = await executeExport(exp)
导出到批次任务
转换生成的导出列表 splitExport 到函数可以执行的任务列表 executeBatch
const exps = await splitExport(exp)
const tasks = exportsToBatchTasks(exps)
进口
分页导入
在多个进口中分割一个进口,同时遵守输入的最大限度
const exp: ImportCreate = {
resource_type: 'customers',
inputs: [
{ ... },
{ ... },
...
{ ... }
]
}
const splitImp: ImportCreate[] = await splitImport(imp)
执行导入
在多个进口中拆分一个导入,同时遵守输入的最大限制,并将其执行
const exp: ImportCreate = {
resource_type: 'customers',
inputs: [
{ ... },
{ ... },
...
{ ... }
]
}
const execImp: ImportResult[] = await executeImport(imp)
导入到批量任务
转换生成的导入列表 splitImport 到函数可以执行的任务列表 executeBatch
const imps = await splitImport(imp)
const tasks = importsToBatchTasks(imps)
网络呼号
解除 Payload 的正常状态
该函数以JSON格式输入一个webhook的有效载荷,并将其转换成适当的打字资源,与正式的Typescript SDK一起使用.
const shipment = denormalizePayload<Shipment>(webhookPayload)
SDK 查询助手
包含帮助
这个帮助器可以用来轻松地构建包含在SDK查询参数中使用的数组资源.
说明: 这个
versions资源已经从商务层 API 中删除,在包含的帮助中不再可用.
标准包括
const include: QueryInclude = [ 'market', 'customer', 'customer.customer_group' ]
包含包含帮助
import { Include } from '@commercelayer/sdk-utils'
const include: QueryInclude = [ Include.orders.market.build(), Include.orders.customer.build(), Include.orders.customer.customer_group.build() ]
// The same as above but using a single instance of the orders helper
const io = Include.orders
const includeSingle: QueryInclude = [ io.market.build(), io.customer.build(), io.customer.customer_group.build() ]
包含使用 包含 函数
import { buildInclude } from '@commercelayer/sdk-utils'
const include: QueryInclude = buildInclude(Include.orders.market, Include.orders.customer, Include.orders.customer.customer_group)
将资源添加到已有的查询过滤器中
import { Include } from '@commercelayer/sdk-utils'
const queryFilter: QueryParams = {}
const io = Include.orders
io.market.addTo(queryFilter)
io.customer.addTo(queryFilter)
io.customer.customer_group.addTo(queryFilter)
过滤帮助
这个帮助可以用来方便地构建包含滤波器上游的物体来用于SDK查询参数.
说明: 这个
versions资源已经从商务层 API 中移除,并且已无法在过滤器帮助中获取.
标准过滤器
const filter: QueryFilter = {
number_eq: '123',
market_reference_eq: 'MKT',
reference_or_customer_customer_group_reference_eq: 'REF',
status_in: 'placed,approved,cancelled',
reference_origin_not_null: 'true'
}
带有过滤帮助器的过滤器
import { Filter } from '@commercelayer/sdk-utils'
const filter: QueryFilter = {
...Filter.orders.number.eq('123'),
...Filter.orders.market.reference.eq('MKT'),
...Filter.orders.reference.or.customer.customer_group.reference.eq('REF'),
...Filter.orders.status.in('placed', 'approved', 'cancelled'),
...Filter.orders.reference_origin.not_null()
}
// The same as above but using a single instance of the orders helper
const of = Filter.orders
const filterSingle: QueryFilter = {
...of.number.eq('123'),
...of.market.reference.eq('MKT'),
...of.reference.or.customer.customer_group.reference.eq('REF'),
...of.status.in('placed', 'approved', 'cancelled'),
...of.reference_origin.not_null()
}
使用过滤器 构建过滤器 函数
import { buildFilter } from '@commercelayer/sdk-utils'
const filter: QueryFilter = buildFilter(
of.number.eq('123'),
of.market.reference.eq('MKT'),
of.reference.or.customer.customer_group.reference.eq('REF'),
of.status.in('placed', 'approved', 'cancelled'),
of.reference_origin.not_null()
)