庫存能見度公用 API

發行項
05/17/2024

附註

Azure Active Directory 現在是 Microsoft Entra 識別碼。深入了解

本文說明庫存能見度提供的公用 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`	Get	使用 get 方式查詢
`/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`	張貼	利用產品搜尋進行 Post 索引查詢 (API)
`/api/environment/{environmentId}/onhand/productsearch/exactquery`	張貼	利用產品搜尋進行 Post 精確查詢 (API)

附註

路徑的 {environmentId} 部分是 Microsoft Dynamics Lifecycle Services 中的環境識別碼。

批量 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 環境識別碼。
- 設定所有其他值，如範例中所示。
透過提交具有以下屬性的 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

附註

The https://securityservice.operations365.dynamics.com/tokenURL 是安全性服務的通用 URL。當您調用 URL 時，第一個回覆是一個 http 重新導向回覆，在回應標頭中帶有狀態代碼 307 ，以及一個帶有「位置」鍵的項目，其中包含安全性服務的目標 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`	特定變更事件的唯一識別碼。如果因服務失敗而產生重新提交，則此識別碼會用於確保相同事件不會在系統中被計算兩次。
`organizationId`	連結到事件的組織識別碼。此值對應到 Supply Chain Management 中的組織或資料區域識別碼。
`productId`	產品識別碼。
`quantities`	現有數量必須更改的數量。例如，如果將 10 本新書新增到層架，則此值將是 `quantities:{ shelf:{ received: 10 }}`。如果三本書從層架移除或出售，此值將為 `quantities:{ shelf:{ sold: 3 }}`。
`dimensionDataSource`	過帳變更事件和查詢中使用維度的資料來源。如果您指定資料來源，則可以使用於自指定資料來源的自訂維度。庫存能見度可以使用維度設定將自訂維度對應到一般預設維度。如果 `dimensionDataSource` 值未指定，您只能在您的查詢中使用一般的基本維度。
`dimensions`	動態鍵值對。這些值對應到 Supply Chain Management 中的部分維度。但是，您也可以新增自訂維度 (例如，來源) 以指示事件是來自 Supply Chain Management 還是來自外部系統。

附註

如果你的資料分割區規則被設定為按產品識別碼，則 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 恤產品張貼一筆變更事件。此事件將增加 1 件 T 恤產品數量。

{
    "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 將為「成功」，而 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 值查詢多達 5,000 項個別品項。每個查詢中也可以指定多項 siteID 和 locationID。當你的資料分割區規則被設定為按地點時，最大限制由以下等式定義：

NumOf(站點 ID) × NumOf(位置 ID) <= 10,000。

使用 post 方式查詢

郵寄查詢 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 參數。如需詳細資訊，請參閱現有的索引設定。

依產品識別碼查詢儲存的資料

當您的資料分割區規則被設定為按產品識別碼，適用於此部分在這種情況下，兩個 filters 欄位是必填：organizationId、productId。

organizationId 應該是一個只包含一個值的陣列。
productId 應該是一個至少包含一個值的陣列。

與按位置儲存資料不同，如果您不指定 siteId 和 locationId 的值，則每個產品識別碼的庫存資訊都將在所有站點和/或位置進行匯總。

附註

如果您已啟用現有變更計畫和可承諾量 (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"]。

使用 get 方式查詢

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]

此處是一個樣本 get URL。此 get 要求與之前提供的 post 樣本完全相同。

/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 方法進行手邊精確查詢查詢

透過 post API 進行的即時精確查詢有兩個版本。下表概述了這些差異。

API 版本 1.0	API 版本 2.0
只能查詢一個組織 ID。	可以查詢多個組織 ID。

即時精準查詢 post 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 可能包含一或多個值。如果是空陣列，則所有產品將退回。
只有在您的資料分割區規則被設定為按地點時，siteId 和 locationId 在 dimensions 陣列中才是必需。在這個情況下，它們可以依任何順序與其他元素一起出現。
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
}

即時精準查詢 post 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 方式精確查詢

附註

當您張貼使用產品搜尋的庫存能見度查詢時，請使用 productSearch 要求參數 (內部包含 ProductAttributeQuery 物件)，以按產品識別碼尋找或篩選。較新的 API 不再支援要求本文中較舊的 productid 要求參數。

必要條件

您的系統必須先滿足下列需求，您才能開始使用產品搜尋 API：

您必須執行 Dynamics 365 Supply Chain Management 10.0.36 或更新版本。
必須安裝庫存能見度版本 1.2.2.54 或更新版本，並依照安裝及設定庫存能見度的說明來設定。
必須安裝庫存能見度搜尋服務並依照設定庫存能見度的產品說明中的說明來設定。

產品搜尋合約

產品搜尋合約定義了與產品搜尋 API 通訊的規則。它提供一種標準化的方式來描述產品搜尋功能的功能和行為。因此，使用者可以更輕鬆地理解、互動和建立使用庫存能見度 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"
                    }
                ]
            }
        ]
    },
}

下表說明合約中使用的欄位。

欄位識別碼	說明
`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 位於庫存能見度分配。

共用方式為

庫存能見度公用 API

驗證

建立現有變更事件

建立一個現有變更事件

建立多個變更事件

設定/覆寫現有數量

建立保留事件

建立一個保留事件

建立多個保留事件

還原保留事件

還原一個保留事件

還原多個保留事件

清理保留資料

查詢現有

使用 post 方式查詢

貼文查詢 API 版本 1.0

按位置查詢儲存的資料

依產品識別碼查詢儲存的資料

貼文查詢 API 2.0 版

使用 get 方式查詢

現有精確查詢

使用 post 方法進行手邊精確查詢查詢

即時精準查詢 post API 1.0 版

即時精準查詢 post API 2.0 版

透過產品搜尋進行查詢

必要條件

產品搜尋合約

透過產品搜尋進行查詢

利用產品搜尋進行精確查詢

可承諾量

配置

意見反應

其他資源