Inventory Visibility 公共 API

项目
05/17/2024

注意

Azure Active Directory 现在是 Microsoft Entra ID。了解详细信息

本文介绍库存可见性提供的公共 API。

库存可见性加载项的公共 REST API 为集成提供几个特定终结点。它支持四种主要交互类型：

从外部系统发布对加载项的现有库存量更改
从外部系统设置或覆盖加载项中的现有库存数量
从外部系统将预留事件过帐到加载项
从外部系统查询当前的现有数量

下表列出了当前可用的 API：

路径	方法	描述
`/api/environment/{environmentId}/onhand`	发布	创建一个现有库存更改事件
`/api/environment/{environmentId}/onhand/bulk`	发布	创建多个更改事件
`/api/environment/{environmentId}/setonhand/{inventorySystem}/bulk`	发布	设置/覆盖现有库存数量
`/api/environment/{environmentId}/onhand/reserve`	发布	创建一个软预留事件
`/api/environment/{environmentId}/onhand/reserve/bulk`	发布	创建多个软预留事件
`/api/environment/{environmentId}/onhand/unreserve`	发布	撤销一个软预留事件
`/api/environment/{environmentId}/onhand/unreserve/bulk`	发布	撤销多个软预留事件
`/api/environment/{environmentId}/onhand/reserve/resyncjob`	发布	清理预留数据
`/api/environment/{environmentId}/onhand/changeschedule`	发布	创建一个计划现有库存更改
`/api/environment/{environmentId}/onhand/changeschedule/bulk`	发布	创建多个带日期的现有量更改
`/api/environment/{environmentId}/onhand/indexquery`	发布	使用 post 方法查询（推荐）
`/api/environment/{environmentId}/onhand`	获取	使用获取方法查询
`/api/environment/{environmentId}/onhand/exactquery`	发布	使用 post 方法进行精确查询
`/api/environment/{environmentId}/allocation/allocate`	发布	创建一个分配事件
`/api/environment/{environmentId}/allocation/unallocate`	发布	创建一个取消分配事件
`/api/environment/{environmentId}/allocation/reallocate`	发布	创建一个重新分配事件
`/api/environment/{environmentId}/allocation/consume`	发布	创建一个使用事件
`/api/environment/{environmentId}/allocation/query`	发布	查询分配结果
`/api/environment/{environmentId}/onhand/productsearch/indexquery`	发布	发布使用产品搜索索引查询
`/api/environment/{environmentId}/onhand/productsearch/exactquery`	发布	发布使用产品搜索精确查询

注意

此路径的 {environmentId} 部分是 Microsoft Dynamics Lifecycle Services 中的环境 ID。

批量 API 最多可为每个请求返回 512 条记录。

身份验证

平台安全令牌用于调用库存可见性公共 API。因此，您必须使用 Microsoft Entra 应用程序生成 Microsoft Entra 令牌。然后，必须使用 Microsoft Entra 令牌从安全服务获取访问令牌。

若要获取安全服务令牌，请执行以下步骤。

登录 Azure 门户，然后将其用于查找 Dynamics 365 Supply Chain Management 应用的 clientId 和 clientSecret 值。
通过提交具有以下属性的 HTTP 请求来提取 Microsoft Entra 令牌 (aadToken)：
- URL：https://login.microsoftonline.com/${aadTenantId}/oauth2/v2.0/token
- 方法：GET
- 正文内容（窗体数据）：
  
  键值
  
  client_id ${aadAppId}
  
  client_secret ${aadAppSecret}
  
  grant_type client_credentials
  
  范围 0cdb527f-a8d1-4bf8-9436-b352c68682b2/.default
您应通过响应收到一个 Microsoft Entra 令牌 (aadToken)。标签应类似于以下示例。
```
{
    "token_type": "Bearer",
    "expires_in": "3599",
    "ext_expires_in": "3599",
    "access_token": "eyJ0eX...8WQ"
}
```
创建一个如下示例的 JavaScript 对象表示法 (JSON) 请求。
```
{
    "grant_type": "client_credentials",
    "client_assertion_type": "aad_app",
    "client_assertion": "{Your_Microsoft EntraToken}",
    "scope": "https://inventoryservice.operations365.dynamics.com/.default",
    "context": "{$LCS_environment_id}",
    "context_type": "finops-env"
}
```
请注意以下点：
- client_assertion 值必须是您在上一步中收到的 Microsoft Entra 令牌 (aadToken)。
- context 值必须是要在其中部署加载项的 Lifecycle Services 环境 ID。
- 如示例中所示设置所有其他值。
通过提交具有以下属性的 HTTP 请求来获取访问令牌 (access_token)：
- URL：https://securityservice.operations365.dynamics.com/token
- 方法：POST
- HTTP 标题：包含 API 版本。（密钥为 Api-Version，值为 1.0。）
- 正文内容：包括您在上一步中创建的 JSON 请求。
您应通过响应收到一个访问令牌 (access_token)。必须将此令牌用作持有者令牌来调用库存可见性 API。下面是一个示例。
```
{
    "access_token": "{Returned_Token}",
    "token_type": "bearer",
    "expires_in": 3600
}
```

键	值
client_id	${aadAppId}
client_secret	${aadAppSecret}
grant_type	client_credentials
范围	0cdb527f-a8d1-4bf8-9436-b352c68682b2/.default

纸币

https://securityservice.operations365.dynamics.com/token URL 是安全服务的通用 URL。调用该 URL 时，第一个响应是一个在响应标头中带有状态代码 307 的 http 重定向响应，以及一个带有键“Location”（其中包含安全服务的目标 URL）的条目。该 URL 采用下面的格式：https://gw.{$geo}-il101.gateway.prod.island.powerapps.com/securityservice/token。例如，如果您的环境位于美国地理区域内，则 URL 可能为 https://gw.us-il101.gateway.prod.island.powerapps.com/securityservice/token。如果您无法接受 307 响应状态代码，您可以根据您的 FinOps 环境位置手动构建实际 URL。最简单的方法就是使用浏览器打开 https://gw.as-il101.gateway.prod.island.powerapps.com/securityservice/token，然后复制地址栏中的地址。

创建现有库存更改事件

有两个 API 可用于创建现有库存更改事件：

创建一个记录：/api/environment/{environmentId}/onhand
创建多个记录：/api/environment/{environmentId}/onhand/bulk

下表汇总了 JSON 正文中各字段的含义。

字段 ID	Description
`id`	特定更改事件的唯一 ID。如果由于服务失败而导致重新提交，此 ID 用于确保同一事件不会在系统中被计算两次。
`organizationId`	链接到事件的组织的标识符。此值将在 Supply Chain Management 中映射到组织或数据区域 ID。
`productId`	产品的标识符。
`quantities`	必须充当现有库存数量的更改量的数量。例如，如果将 10 本新帐簿添加到货位，则此值将为 `quantities:{ shelf:{ received: 10 }}`。如果从货位中移除或出售了三本帐簿，则此值将为 `quantities:{ shelf:{ sold: 3 }}`。
`dimensionDataSource`	在发布更改事件和查询中使用的维度的数据源。如果指定数据源，您可以使用来自指定数据源的自定义维度。库存可见性可使用维度配置将自定义维度映射到常规默认维度。如果未指定 `dimensionDataSource` 值，则只能在查询中使用常规基础维度。
`dimensions`	动态键-值对。这些值将映射到 Supply Chain Management 中的某些维度。但是，也可以添加自定义维度（例如，来源）以指示事件来自 Supply Chain Management 还是外部系统。

注意

如果数据分区规则设置为按产品 ID，siteId 和 locationId 为可选维度。否则，它们是必需的维度。此规则也适用于分配、软预留和更改计划 API。

以下各小节提供了说明如何使用这些 API 的示例。

创建一个现有库存更改事件

此 API 用于创建一个现有库存更改事件。

Path:
    /api/environment/{environmentId}/onhand
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        id: string,
        organizationId: string,
        productId: string,
        dimensionDataSource: string, # Optional
        dimensions: {
            [key:string]: string,
        },
        quantities: {
            [dataSourceName:string]: {
                [key:string]: number,
            },
        },
    }

以下示例显示示例正文内容。在此示例中，公司有一个销售点 (POS) 系统，用于处理店内交易，因而会处理库存变化。客户将一件红色 T 恤退回您的商店。为反映此变动，您为 T 恤产品发布了一个更改事件。此事件将使 T 恤杉产品的数量加 1。

{
    "id": "Test201",
    "organizationId": "usmf",
    "productId": "T-shirt",
    "dimensionDataSource": "pos",
    "dimensions": {
        "siteId": "1",
        "locationId": "11",
        "posMachineId": "0001",
        "colorId": "red"
    },
    "quantities": {
        "pos": {
            "inbound": 1
        }
    }
}

以下示例显示不带 dimensionDataSource 的示例正文内容。在此示例中，dimensions 将为基础维度。如果设置 dimensionDataSource，dimensions 可以是数据源维度或基础维度。

{
    "id": "Test202",
    "organizationId": "usmf",
    "productId": "T-shirt",
    "dimensions": {
        "siteId": "1",
        "locationId": "11",
        "colorId": "red"
    },
    "quantities": {
        "pos": {
            "inbound": 1
        }
    }
}

创建多个更改事件

此 API 可以创建更改事件，就像单事件 API 一样。唯一的不同是此 API 可以同时创建多个记录。因此，Path 和 Body 值不同。对于此 API，Body 提供一组记录。最大记录数为 512。因此，现有量更改批量 API 一次最多可以支持 512 个更改事件。

例如，零售店 POS 机处理以下两个交易：

一个一件红色 T 恤的退货单
一笔三件黑色 T 恤的销售交易

在这种情况下，您可以在一个 API 调用中同时包含两个库存更新。

Path:
    /api/environment/{environmentId}/onhand/bulk
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [
        {
            id: string,
            organizationId: string,
            productId: string,
            dimensionDataSource: string, # Optional
            dimensions: {
                [key:string]: string,
            },
            quantities: {
                [dataSourceName:string]: {
                    [key:string]: number,
                },
            },
        },
        ...
    ]

以下示例显示示例正文内容。

[
    {
        "id": "Test203",
        "organizationId": "usmf",
        "productId": "T-shirt",
        "dimensionDataSource": "pos",
        "dimensions": {
            "SiteId": "Site1",
            "LocationId": "11",
            "posMachineId": "0001"
            "colorId": "red"
        },
        "quantities": {
            "pos": { "inbound": 1 }
        }
    },
    {
        "id": "Test204",
        "organizationId": "usmf",
        "productId": "T-shirt",
        "dimensions": {
            "siteId": "1",
            "locationId": "11",
            "colorId": "black"
        },
        "quantities": {
            "pos": { "outbound": 3 }
        }
    }
]

设置/覆盖现有库存数量

设置现有库存 API 覆盖指定产品的当前数据。此功能通常用于进行库存盘点更新。例如，在每日库存盘点期间，商店可能会发现某种红色 T 恤的实际现有库存为 100。因此，无论之前的数量是多少，POS 入站数量都必须更新为 100。您可以使用此 API 替代现有值。

Path:
    /api/environment/{environmentId}/setonhand/{inventorySystem}/bulk
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [
        {
            id: string,
            organizationId: string,
            productId: string,
            dimensionDataSource: string, # Optional
            dimensions: {
                [key:string]: string,
            },
            quantities: {
                [dataSourceName:string]: {
                    [key:string]: number,
                },
            },
            modifiedDateTimeUTC: datetime,
        },
        ...
    ]

以下示例显示示例正文内容。此 API 的行为与本文前面的创建现有库存更改事件一节中介绍的 API 的行为不同。在此示例中，将把 T 恤杉产品的数量设置为 1。

[
    {
        "id": "Test204",
        "organizationId": "usmf",
        "productId": "T-shirt",
        "dimensionDataSource": "pos",
        "dimensions": {
            "SiteId": "1",
            "LocationId": "11",
            "posMachineId": "0001"
            "colorId": "red"
        },
        "quantities": {
            "pos": {
                "inbound": 100
            }
        }
    }
]

创建预留事件

若要使用预留 API，必须开启预留功能并完成预留配置。有关详细信息（包括数据流和示例场景），请参阅库存可见性预留。

创建一个预留事件

可以针对不同数据源设置进行预留。若要配置这种类型的预留，请先在 dimensionDataSource 参数中指定数据源。然后，在 dimensions 参数中根据目标数据源中的维度设置指定维度。

调用预留 API 时，可以通过在请求正文中指定 ifCheckAvailForReserv 布尔值参数来控制预留验证。值为 True 表示需要验证，而值为 False 则表示不需要验证。默认值为 True。

如果要撤销预留或撤消指定的库存数量，请将数量设置为负数，然后将 ifCheckAvailForReserv 参数设置为 False 以跳过验证。还有一个专用的撤消 API 也可以完成此任务。两种方法的不同之处仅在于调用这两个 API 的方式。将 reservationId 与撤消 API 结合使用可以更轻松地撤销特定的预留事件。有关更多信息，请参阅撤消一个预留事件一节。

Path:
    /api/environment/{environmentId}/onhand/reserve
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        id: string,
        organizationId: string,
        productId: string,
        dimensionDataSource: string,
        dimensions: {
            [key:string]: string,
        },
        quantityDataSource: string, # optional
        quantities: {
            [dataSourceName:string]: {
                [key:string]: number,
            },
        },
        modifier: string,
        quantity: number,
        ifCheckAvailForReserv: boolean,
    }

以下示例显示示例正文内容。

{
    "id": "reserve-0",
    "organizationId": "SCM_IV",
    "productId": "iv_contoso_product",
    "quantity": 1,
    "quantityDataSource": "iv",
    "modifier": "softReservOrdered",
    "ifCheckAvailForReserv": true,
    "dimensions": {
        "siteId": "iv_contoso_site",
        "locationId": "iv_contoso_location",
        "colorId": "red",
        "sizeId": "small"
    }
}

以下示例显示了一个成功的响应。

{
    "reservationId": "RESERVATION_ID",
    "id": "ohre~id-822-232959-524",
    "processingStatus": "success",
    "message": "",
    "statusCode": 200
}

创建多个预留事件

此 API 是单事件 API 的批量版本。

Path:
    /api/environment/{environmentId}/onhand/reserve/bulk
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [
        {
            id: string,
            organizationId: string,
            productId: string,
            dimensionDataSource: string,
            dimensions: {
                [key:string]: string,
            },
            quantityDataSource: string, # optional
            quantities: {
                [dataSourceName:string]: {
                    [key:string]: number,
                },
            },
            modifier: string,
            quantity: number,
            ifCheckAvailForReserv: boolean,
        },
        ...
    ]

撤销预留事件

撤消 API 用作预留事件的撤销操作。它提供了一种方法来撤销由 reservationId 指定的预留事件或减少预留数量。

撤销一个预留事件

创建预留时，reservationId 将包含在响应正文中。您必须提供相同的 reservationId 才能取消预留，并包括用于预留 API 调用的相同 organizationId、productId 和 dimensions。最后，指定表示要从先前预留中释放的项目数的 OffsetQty 值。预留可以完全或部分撤销，具体取决于指定的 OffsetQty. 例如，如果预留了 100 个单位的项目，您可以指定 OffsetQty: 10 来撤消初始预留量 10。

Path:
    /api/environment/{environmentId}/onhand/unreserve
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        id: string,
        organizationId: string,
        productId: string,
        reservationId: string,
        dimensions: {
            [key:string]: string,
        },
        OffsetQty: number
    }

以下代码显示了正文内容的示例。

{
    "id": "unreserve-0",
    "organizationId": "SCM_IV",
    "productId": "iv_contoso_product",
    "reservationId": "RESERVATION_ID",
    "dimensions": {
        "siteid":"iv_contoso_site",
        "locationid":"iv_contoso_location",
        "ColorId": "red",
        "SizeId": "small"
    },
    "OffsetQty": 1
}

以下代码显示了成功响应正文的示例。

{
    "reservationId": "RESERVATION_ID",
    "totalInvalidOffsetQtyByReservId": 0,
    "id": "ohoe~id-823-11744-883",
    "processingStatus": "success",
    "message": "",
    "statusCode": 200
}

注释

在响应正文中，当 OffsetQty 小于或等于预留数量时，processingStatus 将是“success”，totalInvalidOffsetQtyByReservId 将是 0。

如果 OffsetQty 大于预留量，processingStatus 将是“partialSuccess”，totalInvalidOffsetQtyByReservId 将是 OffsetQty 与预留量之间的差值。

例如，如果预留的数量为 10，OffsetQty 的值为 12，totalInvalidOffsetQtyByReservId 将是 2。

撤销多个预留事件

此 API 是单事件 API 的批量版本。

Path:
    /api/environment/{environmentId}/onhand/unreserve/bulk
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [      
        {
            id: string,
            organizationId: string,
            productId: string,
            reservationId: string,
            dimensions: {
                [key:string]: string,
            },
            OffsetQty: number
        }
        ...
    ]

清理预留数据

清理预留数据 API 用于清理历史预留数据。正文应该是数据源的列表。如果该列表为空，将清理所有数据源。

Path:
    /api/environment/{environmentId}/onhand/reserve/resyncjob
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [      
        "iv",
        "pos"
    ]

查询现有库存

使用查询现有库存 API 提取产品的当前现有库存数据。当您需要了解库存时，您可以使用此 API，如当您想要在电子商务网站上查看产品库存水平时，或者当您想要跨区域或在附近的商店和仓库检查产品可用性时。 API 当前最多支持按 productID 值查询 5000 个单个项。也可以在每个查询中指定多个 siteID 值和 locationID 值。当数据分区规则设置为按库位时，通过以下等式设置最大限制：

NumOf（站点 ID）× NumOf（位置 ID） <= 10,000。

使用过帐方法查询

通过帖子查询 API 有两个版本。下表概述了这些差异。

API 版本 1.0	API 版本 2.0
只能查询一个组织 ID。	可以查询多个组织 ID。
最多可查询 10000 个站点和仓库的组合。	可以查询 10000 多个组织 ID、站点和仓库的组合。可以多页返回结果。

以下小节展示了如何使用每个 API 版本。

通过帖子查询 API 版本 1.0

Path:
    /api/environment/{environmentId}/onhand/indexquery
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        dimensionDataSource: string, # Optional
        filters: {
            organizationId: string[],
            productId: string[],
            siteId: string[],
            locationId: string[],
            [dimensionKey:string]: string[],
        },
        groupByValues: string[],
        returnNegative: boolean,
    }

在此请求的正文部分中，dimensionDataSource 是可选参数。如果未设置此参数，将把 filters 视为基础维度。

returnNegative 参数控制结果中是否包含负条目。

按库位查询存储的数据

当数据分区规则设置为按库位时，此部分适用。

organizationId 应该是只包含一个值的数组。
productId 可以包含一个或多个值。如果它是一个空数组，系统将返回指定站点和库位的所有产品。在这种情况下，siteId 和 locationId 不应为空。
siteId 和 locationId 用于分区。您可以在查询现有库存请求中指定多个 siteId 和 locationId 值。如果这两个数组都为空，系统将返回指定产品的所有站点和库位。在这种情况下，productId 不应为空。

我们建议以与索引配置一致的方式使用 groupByValues 参数。有关详细信息，请参阅现有量索引配置。

按产品 ID 查询存储的数据

当数据分区规则设置为按产品 ID 时，此部分适用。在这种情况下，需要两个 filters 字段：organizationId、productId。

organizationId 应该是只包含一个值的数组。
productId 应该是至少包含一个值的数组。

与按库位存储数据时不同，如果您没有指定 siteId 和 locationId 的值，将跨所有站点和/或库位聚合每个产品 ID 的库存信息。

注意

如果您启用了现有库存更改计划和可承诺 (ATP) 功能，您的查询还可以包含 QueryATP 布尔参数，该参数控制查询结果是否包含 ATP 信息。有关详细信息和示例，请参阅库存可见性现有库存更改计划与可承诺。

以下示例显示示例正文内容。它显示您可以从多个位置（仓库）查询现有库存。

{
    "dimensionDataSource": "pos",
    "filters": {
        "organizationId": ["usmf"],
        "productId": ["T-shirt"],
        "siteId": ["1"],
        "locationId": ["11","12","13"],
        "colorId": ["red"]
    },
    "groupByValues": ["colorId", "sizeId"],
    "returnNegative": true
}

以下示例显示如何查询特定站点和位置中的所有产品。

{
    "filters": {
        "organizationId": ["usmf"],
        "productId": [],
        "siteId": ["1"],
        "locationId": ["11"],
    },
    "groupByValues": ["colorId", "sizeId"],
    "returnNegative": true
}

通过帖子查询 API 版本 2.0

Path:
    /api/environment/{environmentId}/onhand/indexquery?pageNumber={pageNumber}&pageSize={pageSize}
Method:
    Post
Headers:
    Api-Version="2.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    # Same as version 1.0

API 2.0 版本的请求格式与 1.0 版本类似，但还支持两个可选参数： pageNumber 和 pageSize，允许系统将单个较大的结果拆分为多个较小的文档。将结果按照仓库进行排序（locationId），使用参数如下，将结果拆分为页面：

pageSize 确定每页返回的仓库数量（locationId 值）。
pageNumber 确定返回的页码。

这种格式的请求返回从仓库编号 （{pageNumber} − 1）× {pageSize} 开始的现有库存数据，并包含下一个 {pageSize} 仓库的数据。

API 2.0 版本使用以下结构的文档进行响应：

{
    Value: { # Response same as Api-Version=1.0 }
    nextLink: onhand/indexquery?pageNumber={pageNumber+1}&pageSize={pageSize}
}

当请求到达最后一个仓库（locationId）时， nextLink 的值为空字符串。

API 版本 2.0 还允许您在请求中指定多个组织 ID。为此，请在请求文档的 organizationId 过滤器中包含以逗号分隔的组织 ID 列表。例如， "organizationId": ["org1", "org2", "org3"]。

使用获取方法查询

Path:
    /api/environment/{environmentId}/onhand
Method:
    Get
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Query(Url Parameters):
    groupBy
    returnNegative
    [Filters]

下面是示例获取 URL。此获取请求与前面提供的过帐示例完全相同。

/api/environment/{environmentId}/onhand?organizationId=SCM_IV&productId=iv_contoso_product&siteId=iv_contoso_site&locationId=iv_contoso_location&colorId=red&groupBy=colorId,sizeId&returnNegative=true

系统不支持使用 GET 方法查询多个组织 ID 的库存。

现有量准确查询

现有量准确查询类似于常规现有量查询，但允许您指定站点和位置之间的映射层次结构。例如，您有以下两个站点：

站点 1，映射到位置 A
站点 2，映射到位置 B

对于常规现有量查询，如果指定 "siteId": ["1","2"] 和 "locationId": ["A","B"]，库存可见性将自动查询以下站点和位置的结果：

站点 1，位置 A
站点 1，位置 B
站点 2，位置 A
站点 2，位置 B

如您所见，常规现有量查询无法识别位置 A 仅存在于站点 1，位置 B 仅存在于站点 2。因此，它会进行冗余查询。为了适应这种分层映射，您可以使用现有量准确查询，在查询正文中指定位置映射。在这种情况下，您将查询并收到仅站点 1、位置 A 和站点 2、位置 B 的结果。

使用 post 方式进行现场精确查询

现存精确邮递查询 API 目前有两个版本。下表概述了这些差异。

API 版本 1.0	API 版本 2.0
只能查询一个组织 ID。	可以查询多个组织 ID。

邮政库存精确查询 API 版本 1.0

Path:
    /api/environment/{environmentId}/onhand/exactquery
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        dimensionDataSource: string, # Optional
        filters: {
            organizationId: string[],
            productId: string[],
            dimensions: string[],
            values: string[][],
        },
        groupByValues: string[],
        returnNegative: boolean,
    }

在此请求的正文部分中，dimensionDataSource 是可选参数。如果未设置此参数，会将 filters 中的 dimensions 视为基础维度。 filters 有四个必填字段：organizationId、productId、dimensions 和 values。

organizationId 中应仅包含一个值，但它仍然是数组。
productId 中可以包含一个或多个值。如果它是空数组，将返回所有产品。
在 dimensions 数组中，当且仅当数据分区规则设置为按库位时，siteId 和 locationId 是必需的。在这种情况下，它们可以按任何顺序与其他元素一起显示。
values 可以包含与 dimensions 对应的一个或多个不同的值元组。

filters 中的 dimensions 将被自动添加到 groupByValues。

returnNegative 参数控制结果中是否包含负条目。

以下示例显示示例正文内容。

{
    "dimensionDataSource": "pos",
    "filters": {
        "organizationId": ["SCM_IV"],
        "productId": ["iv_contoso_product"],
        "dimensions": ["siteId", "locationId", "colorId"],
        "values" : [
            ["iv_contoso_site", "iv_contoso_location", "red"],
            ["iv_contoso_site", "iv_contoso_location", "blue"],
        ]
    },
    "groupByValues": ["colorId", "sizeId"],
    "returnNegative": true
}

以下示例显示如何查询多个站点和位置的所有产品。

{
    "filters": {
        "organizationId": ["SCM_IV"],
        "productId": [],
        "dimensions": ["siteId", "locationId"],
        "values" : [
            ["iv_contoso_site_1", "iv_contoso_location_1"],
            ["iv_contoso_site_2", "iv_contoso_location_2"],
        ]
    },
    "groupByValues": ["colorId", "sizeId"],
    "returnNegative": true
}

邮政现存精确查询 API 2.0 版

Path:
    /api/environment/{environmentId}/onhand/exactquery
Method:
    Post
Headers:
    Api-Version="2.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        dimensionDataSource: string, # Optional
        filters: {
            productId: string[],
            keys: string[],
            values: string[][],
        },
        groupByValues: string[],
        returnNegative: boolean,
    }

API 版本 2.0 与版本 1.0 有以下不同之处：

filters 部分现在有一个 keys 字段，而不是 dimensions 字段。 keys 字段的工作方式与版本 1.0 中的 dimensions 字段类似，但现在还可以包含 organizationId。您可以按任意顺序指定键。
filters 部分不再支持 organizationId 字段。相反，您可以在 organizationId 字段中的维度中包含 keys （例如， keys: ["organizationId", "siteId", "locationId"]），并在 values 字段中的匹配位置定义组织 ID 值（例如， values: ["SCM_IV", "iv_contoso_site_1", "iv_contoso_location_1"]）。

其余字段与 API 1.0 版本相同。

使用产品搜索查询

增强了以下现有查询 API 以支持产品搜索：

使用 post 方法查询
使用 post 方法进行精确查询

纸币

当您发布使用产品搜索的 Inventory Visibility 查询时，使用 productSearch 请求参数（内部包含 ProductAttributeQuery 对象）按产品 ID 查找或筛选。较新的 API 不再支持在请求正文中使用较旧的 productid 请求参数。

先决条件

在开始使用产品搜索 API 之前，您的系统必须满足以下要求：

您必须运行 Dynamics 365 Supply Chain Management 10.0.36 或更高版本。
必须安装和设置 Inventory Visibility 版本 1.2.2.54 或更高版本，如安装和设置 Inventory Visibility 中所述。
必须安装和设置 Inventory Visibility 搜索服务，如设置 Inventory Visibility 的产品搜索中所述。

产品搜索合同

产品搜索合同定义了与产品搜索 API 通信的规则。它提供了一种标准化方法来描述产品搜索功能的功能和行为。因此，用户可以更轻松地理解、交互和生成使用 Inventory Visibility API 的应用程序。

以下示例显示示例合同。

{
    "productFilter": {
        "logicalOperator": "And",
        "conditions": [
            {
                "conditionOperator": "Contains",
                "productName": [
                    "Deluxe"
                ],
            },
        ],
        "subFilters": [
            {
                "conditions": [
                    {
                        "conditionOperator": "IsExactly",
                        "productType": [
                            "Item"
                        ]
                    }
                ]
            }
        ]
    },
    "attributeFilter": {
        "logicalOperator": "Or",
        "conditions": [
            {
                "attributeName": "Weight Limit",
                "attributeTypeName":"PoundDomain",
                "attributeArea": " ProductAttribute",
                "attributeValues": [
                    "370"
                ],
                "conditionOperator": "GreaterEqual"
            }
        ],
        "subFilters": [
            {
                "conditions": [
                    {
                        "attributeName": "Weight Limit",
                        "attributeTypeName":"PoundDomain",
                        "attributeArea": " ProductAttribute",
                        "attributeValues": [
                            "330"
                        ],
                        "conditionOperator": "LessEqual"
                    }
                ]
            }
        ]
    },
}

下表描述了在合同中使用的字段。

字段 ID	描述
`logicalOperator`	可能的值为 `And` 和 `Or`。使用此字段连接多个条件或条件和子筛选器。请注意，`subFilters` 实际上是一个 `productFilter` 或 `attributeFilter` 对象。因此，您可以在 `subFilters` 中有 `subFilters`。
`conditionOperator`	可能的值为 `IsExactly`、`IsNot`、`Contains`、`DoesNotContain`、`BeginsWith`、`IsOneOf`、`GreaterEqual`、`LessEqual` 和 `Between`。
`ProductFilter`	使用此字段以按产品相关信息筛选产品。例如，您可以将合同中的 `productName` 更改为 `Company`、`itemNumber`、`productSearchName`、`productType`、`productName`、`productDescription`、`inventoryUnitSymbol`、`salesUnitSymbol` 或 `purchaseUnitSymbol`，以满足你的业务需求。
`AttributeFilter`	使用此字段以按属性相关信息筛选产品。
`attributeArea`	可能的值为 `ProductAttribute`、`DimensionAttribute` 和 `BatchAttribute`。

使用产品搜索查询

Path:
    /api/environment/{environmentId}/onhand/productsearch/indexquery
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        productSearch: {ProductAttributeQuery contract object inherited from Product Search}
            dimensionDataSource: string, # Optional
            filters: {
                organizationId: string[],
                siteId: string[],
                locationId: string[],
                [dimensionKey:string]: string[],
            },
            groupByValues: string[],
            returnNegative: boolean,
    }

以下示例显示示例正文内容。

{
    "productSearch": {
        "productFilter": {
            "conditions": [
                {
                    "conditionOperator": "contains",
                    "productName": [
                        "speaker cable"
                    ],
                },
            ],
        },
    },
    "returnNegative": true, 
    "filters": 
    {
        "organizationId": ["usmf"], 
        "siteId": ["1"], 
        "locationId": ["13"],
    },
    "groupByValues": ["colorid"],
}

以下示例显示了一个成功的响应。

[
    {
        "productId": "M0030",
        "dimensions": {
            "ColorId": "White",
            "siteid": "1",
            "locationid": "13"
        },
        "quantities": {
            "fno": {
                "arrived": 0,
                "availordered": 20,
                "onorder": 5,
                "ordered": 20,
                "physicalinvent": 0,
                "reservordered": 0,
                "reservphysical": 0,
                "orderedsum": 20,
                "softreserved": 0
            },
            "iv": {
                "ordered": 0,
                "softreserved": 0,
                "softreservphysical": 0,
                "softreservordered": 0,
                "total ordered": 20,
                "total on order": 5,
                "availabletoreserve": 20,
                "totalavailable": 20,
                "totalordered": 20,
                "totalonorder": 5
            },
            "pos": {
                "inbound": 0,
                "outbound": 0
            },
            "@iv": {
                "@allocated": 0
            }
        }
    },
    {
        "productId": "M0030",
        "dimensions": {
            "ColorId": "Black",
            "siteid": "1",
            "locationid": "13"
        },
        "quantities": {
            "fno": {
                "arrived": 0,
                "availordered": 3,
                "ordered": 3,
                "physicalinvent": 0,
                "reservordered": 0,
                "reservphysical": 0,
                "orderedsum": 3,
                "softreserved": 0
            },
            "iv": {
                "ordered": 0,
                "softreserved": 0,
                "softreservphysical": 0,
                "softreservordered": 0,
                "total ordered": 3,
                "availabletoreserve": 3,
                "totalavailable": 3,
                "totalordered": 3
            },
            "pos": {
                "inbound": 0,
                "outbound": 0
            },
            "@iv": {
                "@allocated": 0
            }
        }
    }
]

使用产品搜索精确查询

Path:
    /api/environment/{environmentId}/onhand/productsearch/exactquery
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        productSearch: {ProductAttributeQuery contract object inherited from Product Search}
            dimensionDataSource: string, # Optional
            filters: {
                organizationId: string[],
                dimensions: string[],
                values: string[][],
            },
            groupByValues: string[],
            returnNegative: boolean,
    }

以下示例显示示例正文内容。

{
    "productSearch": {
        "productFilter": {
            "conditions": [
                {
                    "conditionOperator": "contains",
                    "productName": [
                        "speaker cable"
                    ],
                },
            ],
        },
    },
    "filters": {
        "organizationId": ["usmf"],
        "dimensions": ["siteId", "locationId", "colorid"],
        "values" : [
            ["1", "13", "Black"],
        ]
    },
    "groupByValues": [],
    "returnNegative": true
}

以下示例显示了一个成功的响应。

[
    {
        "productId": "M0030",
        "dimensions": {
            "ColorId": "Black",
            "siteid": "1",
            "locationid": "13"
        },
        "quantities": {
            "fno": {
                "arrived": 0,
                "availordered": 3,
                "ordered": 3,
                "physicalinvent": 0,
                "reservordered": 0,
                "reservphysical": 0,
                "orderedsum": 3,
                "softreserved": 0
            },
            "iv": {
                "ordered": 0,
                "softreserved": 0,
                "softreservphysical": 0,
                "softreservordered": 0,
                "total ordered": 3,
                "availabletoreserve": 3,
                "totalavailable": 3,
                "totalordered": 3
            },
            "pos": {
                "inbound": 0,
                "outbound": 0
            },
            "@iv": {
                "@allocated": 0
            }
        }
    }
]

可承诺

您可以设置库存可见性，以可以计划将来的现有库存更改并计算 ATP 数量。 ATP 是可用的并且可以在下一个期间向客户承诺的物料数量。使用 ATP 计算可以大大提高您的订单履行能力。有关如何启用此功能以及如何在启用此功能后通过 API 与库存可见性交互的信息，请参阅库存可见性现有库存更改计划与可承诺。

分配

与分配相关的 API 位于库存可见性分配中。

通过

Inventory Visibility 公共 API

身份验证

创建现有库存更改事件

创建一个现有库存更改事件

创建多个更改事件

设置/覆盖现有库存数量

创建预留事件

创建一个预留事件

创建多个预留事件

撤销预留事件

撤销一个预留事件

撤销多个预留事件

清理预留数据

查询现有库存

使用过帐方法查询

通过帖子查询 API 版本 1.0

按库位查询存储的数据

按产品 ID 查询存储的数据

通过帖子查询 API 版本 2.0

使用获取方法查询

现有量准确查询

使用 post 方式进行现场精确查询

邮政库存精确查询 API 版本 1.0

邮政现存精确查询 API 2.0 版

使用产品搜索查询

先决条件

产品搜索合同

使用产品搜索查询

使用产品搜索精确查询

可承诺

分配

反馈

反馈

其他资源