인벤토리 가시성 공용 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`	게시	예약된 현재고 변경 1개 만들기
`/api/environment/{environmentId}/onhand/changeschedule/bulk`	게시	날짜가 포함된 여러 변경 사항 만들기
`/api/environment/{environmentId}/onhand/indexquery`	게시	post 메서드를 이용한 쿼리(권장됨)
`/api/environment/{environmentId}/onhand`	가져오기	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`	게시	제품 검색으로 색인 쿼리 게시
`/api/environment/{environmentId}/onhand/productsearch/exactquery`	게시	제품 검색으로 정확한 쿼리 게시

참고

경로의 {environmentId} 일부는 Microsoft Dynamics Lifecycle Services의 환경 ID입니다.

대량 API는 각 요청에 대해 최대 512개의 레코드를 반환할 수 있습니다.

인증

플랫폼 보안 토큰은 재고 가시성 공개 API를 호출하는 데 사용됩니다. 따라서 Microsoft Entra 애플리케이션을 사용하여 Microsoft Entra 토큰을 생성해야 합니다. 그런 다음 Microsoft Entra 토큰을 사용하여 보안 서비스에서 access token을 가져와야 합니다.

보안 서비스 토큰을 얻으려면 다음 단계를 따르세요.

Azure Portal에 로그인하고 이를 사용하여 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"
}
```
다음 예제와 유사한 JSON(JavaScript Object Notation) 요청을 공식화합니다.
```
{
    "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 리디렉션 응답과 보안 서비스의 대상 URL이 포함된 "Location" 키가 포함된 항목입니다. 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	설명
`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(Point-of-Sale) 시스템이 있습니다. 고객이 빨간색 티셔츠를 매장에 반품했습니다. 변경 사항을 반영하기 위해 티셔츠 제품에 대한 단일 변경 이벤트를 게시합니다. 이 이벤트는 티셔츠 제품의 수량을 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 기계는 다음 두 가지 트랜잭션을 처리했습니다.

빨간색 티셔츠 1개의 반품 주문 1건
검은색 티셔츠 3장의 판매 트랜잭션 1건

이 경우 하나의 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는 지정된 제품의 현재 데이터를 재정의합니다. 이 기능은 일반적으로 재고 실사 업데이트를 수행하는 데 사용됩니다. 예를 들어 일일 재고 계산 중에 매장에서는 빨간색 티셔츠의 실제 보유 재고가 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의 동작과 다릅니다. 이 샘플에서 티셔츠 제품의 수량은 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가 호출되는 방식에만 있습니다. 예약 취소 API와 함께 reservationId를 사용하면 특정 예약 이벤트를 취소하는 것이 더 쉽습니다. 자세한 내용은 1개의 예약 이벤트 예약 취소 섹션을 참조하세요.

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에서 지정한 예약 이벤트를 취소하거나 예약 수량을 줄이는 방법을 제공합니다.

1개의 예약 이벤트 취소

예약이 생성되면 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 값으로 최대 5,000개의 개별 항목 쿼리를 지원합니다. 여러 siteID 및 locationID 값을 각 쿼리에 지정할 수도 있습니다. 데이터 파티션 규칙이 위치별로 설정된 경우 최대 제한은 다음 방정식으로 정의됩니다.

NumOf(사이트ID) × NumOf(위치ID) <= 10,000.

post 메서드를 이용한 쿼리

게시 API를 통한 쿼리는 두 가지 버전으로 제공됩니다. 다음 표에는 차이점이 요약되어 있습니다.

API 버전 1.0	API 버전 2.0
하나의 조직 ID만 쿼리할 수 있습니다.	여러 조직 ID를 쿼리할 수 있습니다.
사이트 및 창고 조합을 최대 10,000개까지 쿼리할 수 있습니다.	10,000개 이상의 조직 ID, 사이트 및 창고 조합을 쿼리할 수 있습니다. 여러 페이지에 결과를 반환할 수 있습니다.

다음 하위 섹션에서는 각 API 버전을 사용하는 방법을 보여줍니다.

Post 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별로 설정된 경우에 적용됩니다. 이 경우에는 organizationId, productId라는 두 개의 filters 필드가 필요합니다.

organizationId는 정확히 하나의 값을 포함하는 배열이어야 합니다.
productId는 값이 하나 이상 포함된 배열이어야 합니다.

위치별로 데이터를 저장할 때와 달리 siteId 및 locationId 값을 지정하지 않으면 각 제품 ID의 재고 정보가 모든 사이트 및/또는 위치에 걸쳐 집계됩니다.

참고

현재고 변경 일정 및 ATP(수주 가능량) 기능을 활성화한 경우 쿼리 결과에 ATP 정보가 포함되는지 여부를 제어하는 QueryATP 부울 매개 변수도 쿼리에 포함될 수 있습니다. 더 많은 정보와 예시를 보려면 인벤토리 가시성 보유 재고 변경 일정 및 약속 가능 재고를 참조하세요.

다음 예는 샘플 본문 내용을 보여줍니다. 여러 위치(창고)의 보유 재고를 조회할 수 있음을 보여줍니다.

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

다음은 샘플 가져오기 URL입니다. 이 get 요청은 이전에 제공된 포스트 샘플과 정확히 동일합니다.

/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에 대한 인벤토리 쿼리를 지원하지 않습니다.

보유 재고 정확한 쿼리

보유 재고 정확한 쿼리는 일반 직접 쿼리와 비슷하지만 사이트와 위치 간의 매핑 계층 구조를 지정할 수 있다는 점이 다릅니다. 예를 들어 다음과 같은 두 개의 사이트가 있습니다.

위치 A에 매핑된 사이트 1
위치 B에 매핑된 사이트 2

일반 재고 조회의 경우 "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 메서드를 사용한 정확한 쿼리

참고

제품 검색을 사용하는 인벤토리 가시성 쿼리를 게시하는 경우 productSearch 요청 매개 변수(내부에 ProductAttributeQuery 개체 포함)를 사용하여 제품 ID를 찾거나 필터링합니다. 최신 API는 더 이상 요청 본문에서 이전 productid 요청 매개 변수를 지원하지 않습니다.

전제 조건

제품 검색 API 사용을 시작하려면 시스템이 다음 요구 사항을 충족해야 합니다.

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

다음 표에서는 계약에 사용되는 필드에 대해 설명합니다.

필드 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는 인벤토리 가시성 할당에 있습니다.

다음을 통해 공유

인벤토리 가시성 공용 API

인증

하나의 현재고 변경 이벤트 생성

하나의 현재고 변경 이벤트 생성

여러 변경 이벤트 만들기

현재고 수량 설정/재정의

예약 이벤트 생성

하나의 예약 이벤트 생성

여러 예약 이벤트 생성

예약 이벤트 취소

1개의 예약 이벤트 취소

여러 예약 이벤트 취소

예약 데이터 정리

보유 재고 쿼리

post 메서드를 이용한 쿼리

Post API 버전 1.0으로 쿼리

위치별로 저장된 데이터 쿼리

제품 ID별로 저장된 데이터 쿼리

포스트 API 버전 2.0으로 쿼리하기

get 메서드를 이용한 쿼리

보유 재고 정확한 쿼리

Post 메소드를 사용하여 현재 정확한 쿼리 쿼리

API 버전 1.0 이후의 정확한 쿼리

API 버전 2.0 이후의 정확한 쿼리

제품 검색으로 쿼리

전제 조건

제품 검색 계약

제품 검색으로 쿼리

제품 검색으로 정확한 쿼리

약속 가능 재고

할당

피드백

추가 리소스