Udostępnij za pośrednictwem

Publiczne interfejsy API dodatku Inventory Visibility

  • Artykuł

Uwaga

Azure Active Directory jest teraz Tożsamością Microsoft Entra. Dowiedz się więcej

W tym artykule opisano publiczne interfejsy API udostępniane przez dodatek Widoczność magazynu.

Publiczny interfejs API REST w dodatku Widoczność magazynu przedstawia kilka konkretnych punktów końcowych integracji. Obsługuje on cztery główne typy interakcji:

  • Księgowanie dostępnych zmian zapasów w dodatku z systemu zewnętrznego
  • Konfigurowanie lub zastępowanie ilości dostępnych zapasów w dodatku z zewnętrznego systemu
  • Księgowanie zdarzeń rezerwacji w dodatku z systemu zewnętrznego
  • Badanie bieżących ilości dostępnych zapasów z systemu zewnętrznego

W poniższej tabeli przedstawiono obecnie dostępne interfejsy API:

Ścieżka Metoda Opis
/api/environment/{environmentId}/onhand Opublikuj Tworzenie jednego zdarzenia zmiany dostępnych zapasów
/api/environment/{environmentId}/onhand/bulk Opublikuj Tworzenie wielu zdarzeń zmiany
/api/environment/{environmentId}/setonhand/{inventorySystem}/bulk Opublikuj Ustawianie/zastępowanie dostępnych ilości
/api/environment/{environmentId}/onhand/reserve Opublikuj Tworzenie jednego miękkiego zdarzenia rezerwacji
/api/environment/{environmentId}/onhand/reserve/bulk Opublikuj Tworzenie wielumiękkich zdarzeń rezerwacji
/api/environment/{environmentId}/onhand/unreserve Opublikuj Wycofanie jednego miękkiego zdarzenia rezerwacji
/api/environment/{environmentId}/onhand/unreserve/bulk Opublikuj Wycofanie wielu miękkich zdarzeń rezerwacji
/api/environment/{environmentId}/onhand/reserve/resyncjob Opublikuj Czyszczenie danych rezerwacji
/api/environment/{environmentId}/onhand/changeschedule Opublikuj Utwórz jedną zaplanowaną zmianę od ręki
/api/environment/{environmentId}/onhand/changeschedule/bulk Opublikuj Utwórz wiele zaplanowanych zmian od ręki z datami
/api/environment/{environmentId}/onhand/indexquery Opublikuj Zapytanie przy użyciu metody post (zalecane)
/api/environment/{environmentId}/onhand Pobierz Zapytanie przy użyciu metody GET
/api/environment/{environmentId}/onhand/exactquery Opublikuj Dokładne zapytanie przy użyciu metody POST
/api/environment/{environmentId}/allocation/allocate Opublikuj Utwórz jedno zdarzenie przydziału
/api/environment/{environmentId}/allocation/unallocate Opublikuj Utwórz jedno zdarzenie cofnięcia przydziału
/api/environment/{environmentId}/allocation/reallocate Opublikuj Utwórz jedno zdarzenie ponownego przydziału
/api/environment/{environmentId}/allocation/consume Opublikuj Tworzenie jednego zdarzenia zużycia
/api/environment/{environmentId}/allocation/query Opublikuj Wynik alokacji zapytań
/api/environment/{environmentId}/onhand/productsearch/indexquery Opublikuj Opublikuj zapytanie indeksowe z wyszukiwarką produktów
/api/environment/{environmentId}/onhand/productsearch/exactquery Opublikuj Opublikuj dokładne zapytanie z wyszukiwarką produktów

Uwaga

Część ścieżki {environmentId} jest identyfikatorem środowiska w usługach Microsoft Dynamics Lifecycle Services.

API zbiorcze może zwrócić maksymalnie 512 rekordów dla każdego żądania.

Uwierzytelnianie

Token zabezpieczeń platformy służy do wywołania publicznego interfejsu API Widoczność magazynu. Dlatego należy wygenerować token Microsoft Entra przy użyciu aplikacji Microsoft Entra. Następnie należy użyć tokenu Microsoft Entra, aby uzyskać token dostępu z usługi zabezpieczeń.

Procedura uzyskiwania tokenu usługi zabezpieczeń jest następująca.

  1. Zaloguj się do portalu Azure i użyj go, aby znaleźć wartości clientId i clientSecret dla swojej aplikacji Dynamics 365 Supply Chain Management.

  2. Pobierz token usługi Microsoft Entra (aadToken), przesyłając żądanie HTTP z następującymi właściwościami:

    • URL:https://login.microsoftonline.com/${aadTenantId}/oauth2/v2.0/token

    • Metoda:GET

    • Treść (dane formularza):

      Klucz Wartość
      client_id ${aadAppId}
      client_secret ${aadAppSecret}
      grant_type client_credentials
      zakres 0cdb527f-a8d1-4bf8-9436-b352c68682b2/.domyślne

    Odpowiedź powinna zawierać token Microsoft Entra (aadToken). Powinna ona przypominać następujący przykład.

    {
    "token_type": "Bearer",
    "expires_in": "3599",
    "ext_expires_in": "3599",
    "access_token": "eyJ0eX...8WQ"
}

  3. Sformułuj żądanie JavaScript Object Notation (JSON) przypominające następujący przykład.

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

    Należy uwzględnić następujące informacje:

    • Wartość client_assertion musi być tokenem Microsoft Entra (aadToken) otrzymanym w poprzednim kroku.
    • Wartość context musi być identyfikatorem środowiska Lifecycle Services, w którym ma zostać wdrożony dodatek.
    • Ustaw wszystkie inne wartości, tak jak pokazano w przykładzie.

  4. Pobierz token usługi (access_token), przesyłając żądanie HTTP z następującymi właściwościami:

    • URL:https://securityservice.operations365.dynamics.com/token
    • Metoda:POST
    • Nagłówek HTTP: zawiera wersję API. (Klucz to Api-Version, a wartość to 1.0.)
    • Treść: umożliwia dołączenie żądania JSON utworzonego w poprzednim kroku.

    Odpowiedź powinna zawierać token dostępu (access_token). Musisz użyć tego tokenu do wywołania interfejsu API Widoczność magazynu. Oto przykład.

    {
    "access_token": "{Returned_Token}",
    "token_type": "bearer",
    "expires_in": 3600
}

Banknot

Adres URL https://securityservice.operations365.dynamics.com/token jest ogólnym adresem URL dla usługi zabezpieczeń. Gdy wywołasz adres URL, pierwsza odpowiedź to odpowiedź przekierowywania HTTP z kodem stanu 307 w nagłówkach odpowiedzi oraz wpisem z kluczem „Lokalizacja”, który zawiera docelowy adres URL dla usługi zabezpieczeń. Adres URL jest w następującym formacie: https://gw.{$geo}-il101.gateway.prod.island.powerapps.com/securityservice/token. Na przykład, jeśli środowisko lokalizuje dane w lokalizacji geograficznej w Stanów Zjednoczonych, adres URL może mieć lokalizację https://gw.us-il101.gateway.prod.island.powerapps.com/securityservice/token. Jeśli kod stanu odpowiedzi 307 jest dla Ciebie nie do przyjęcia, możesz ręcznie utworzyć rzeczywisty adres URL zgodnie z lokalizacją środowiska FinOps. Najprostszy sposób to otwarcie https://gw.as-il101.gateway.prod.island.powerapps.com/securityservice/token za pomocą przeglądarki, a następnie skopiowanie adresu na pasku adresu.

Tworzenie zdarzeń zmiany dostępnych zapasów

Istnieją dwa interfejsy API do tworzenia zdarzeń zmiany dostępnych zapasów:

  • Tworzenie jednego rekordu: /api/environment/{environmentId}/onhand
  • Tworzenie wielu rekordów: /api/environment/{environmentId}/onhand/bulk

W poniższej tabeli podsumowano znaczenie poszczególnych pól w treści JSON.

Identyfikator pola Opis
id Unikatowy identyfikator określonego zdarzenia zmiany. Jeśli komunikacja z usługą nie powiedzie się w trakcie księgowania, ten identyfikator służy do zapewnienia, że to samo zdarzenie nie zostanie zliczone dwukrotnie w systemie.
organizationId Identyfikator organizacji połączonej ze zdarzeniem. Wartość jest mapowana na identyfikator organizacji lub obszaru danych w Supply Chain Management.
productId Identyfikator produktu.
quantities Ilość, o którą musi zostać zmieniona dostępna ilość. Jeśli na przykład na półce zostanie dołożonych 10 nowych książek, ta wartość będzie wynosić quantities:{ shelf:{ received: 10 }}. Jeśli trzy książki zostaną usunięte z półki lub sprzedane, ta wartość będzie wynosić quantities:{ shelf:{ sold: 3 }}.
dimensionDataSource Źródło danych wymiarów używanych w zdarzeniu zmiany księgowania i zapytaniu. W przypadku określenia źródła danych można wykorzystać niestandardowe wymiary z określonego źródła danych. Dodatek Widoczność magazynu może używać konfiguracji wymiarów do mapowania niestandardowych wymiarów na ogólne wymiary domyślne. Jeśli nie określiło wartości dimensionDataSource, w zapytaniach można stosować tylko ogólne wymiary podstawowe.
dimensions Dynamiczna para klucz-wartość. Te wartości są mapowane na niektóre wymiary w Supply Chain Management. Można jednak dodać również wymiary niestandardowe (na przykład Źródło), aby wskazać, czy zdarzenie pochodzi z Supply Chain Management, czy z systemu zewnętrznego.

Uwaga

Jeśli reguła partycji danych jest ustawiona jako Według identyfikator produktu, siteId i locationId są wymiarami opcjonalnymi. W przeciwnym razie będą one wymagane. Ta reguła dotyczy także alokacji, rezerwacji wstępnych i zmieniania interfejsów API harmonogramu.

Poniższe podsekcji zawierają przykłady, które pokazują sposób używania tych interfejsów API.

Tworzenie jednego zdarzenia zmiany dostępnych zapasów

Ten interfejs API tworzy jedno zdarzenie zmiany dostępnych zapasów.

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

W poniższym przykładzie pokazano zawartość przykładowej treści. W tym przykładzie firma ma system punktu sprzedaży (POS), który przetwarza transakcje w sklepie, a tym samym zmiany zapasów. Klient zwrócił do Twojego sklepu czerwoną koszulkę. Aby odzwierciedlić zmianę, publikujesz pojedyncze zdarzenie zmiany dla produktu T-shirt. To zdarzenie spowoduje zwiększenie ilości produktu T-shirt o 1.

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

W poniższym przykładzie pokazano zawartość przykładowej treści bez dimensionDataSource. W takim przypadku element dimensions będzie wymiarami bazowymi. Jeśli dimensionDataSource jest ustawiony, dimensions mogą być wymiarami źródłowymi danych lub wymiarami bazowymi.

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

Tworzenie wielu zdarzeń zmiany

Ten interfejs API może tworzyć zdarzenia zmian, tak jak może to być interfejs API jednego zdarzenia. Jedyną różnicą jest to, że ten interfejs API może jednocześnie tworzyć wiele rekordów. W związku z tym wartości Path i Body są różne. W tym interfejsie API Body dostarcza tablicę rekordów. Maksymalna dozwolona liczba rekordów wynosi 512. W związku z tym interfejs API masowych zmian dostępnych pod ręką może obsługiwać do 512 zdarzeń zmian jednocześnie.

Na przykład w aplikacji Retail Store POS są przetwarzane następujące dwie transakcje:

  • Zamówienie zwrotu jednej czerwonej koszulki
  • Jedna transakcja sprzedaży trzech czarnych koszulek

W takim przypadku możesz uwzględnić obie aktualizacje zapasów w jednym wywołaniu 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,
                },
            },
        },
        ...
    ]

W poniższym przykładzie pokazano zawartość przykładowej treści.

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

Ustawianie/zastępowanie dostępnych ilości

Interfejs Ustaw dostępną ilość umożliwia zastąpienie bieżących danych określonego produktu. Ta funkcja jest zazwyczaj używana do aktualizacji inwentaryzacji zapasów. Na przykład podczas codziennego inwentaryzacji sklep może stwierdzić, że rzeczywisty zapas czerwonej koszulki wynosi 100. W związku z tym ilość przychodząca w punkcie sprzedaży musi zostać zaktualizowana do 100, niezależnie od tego, jaka była poprzednia ilość. Ten interfejs API umożliwia zastąpienie istniejącej wartości.

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

W poniższym przykładzie pokazano zawartość przykładowej treści. Zachowanie tego interfejsu API różni się od zachowania interfejsów API, które opisano w sekcji Tworzenie zdarzeń zmiany dostępnych zapasów we wcześniejszej części tego artykułu. W tym przykładzie ilość produktu T-shirt przybiera wartość 1.

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

Tworzenie zdarzeń rezerwacji

Aby korzystać z interfejsu API rezerwacji, należy włączyć funkcję rezerwacji i dokończyć konfigurację rezerwacji. Aby uzyskać więcej informacji (w tym przepływ danych i przykładowy scenariusz), zobacz Rezerwacje Widoczności magazynu.

Tworzenie jednego zdarzenia rezerwacji

Rezerwacji można dokonać w różnych ustawieniach źródła danych. Aby skonfigurować ten typ rezerwacji, najpierw określ źródło danych w parametrze dimensionDataSource. Następnie w parametrze dimensions określ wymiary zgodnie z ustawieniami wymiarów w docelowym źródle danych.

Po wywołaniu interfejsu API rezerwacji można kontrolować walidacje rezerwacji, określając parametr logiczny ifCheckAvailForReserv w treści żądania. Wartość True oznacza, że walidacja jest wymagana, podczas gdy wartość False oznacza, że walidacja nie jest wymagana. Wartością domyślną jest True.

Aby wycofać rezerwację lub cofnąć rezerwację określonych ilości magazynowych, ustaw ilość na wartość ujemną i ustaw parametr ifCheckAvailForReserv na False, aby pominąć weryfikację. Istnieje również dedykowany interfejs API cofania rezerwacji do wykonania tej samej czynności. Różnica polega tylko na sposobu wywoływania tych dwóch interfejsów API. Wycofanie określonego zdarzenia rezerwacji przy użyciu reservationId z interfejsem API wycofaj rezerwację jest łatwiejsze. Aby uzyskać więcej informacji, zobacz sekcję Wycofanie rezerwacji jednego zdarzenia rezerwacji.

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

W poniższym przykładzie pokazano zawartość przykładowej treści.

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

W poniższym przykładzie pokazano odpowiedź pomyślną.

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

Tworzenie wielu zdarzeń rezerwacji

Ten interfejs API jest wersją masową interfejsu API jednego zdarzenia.

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

Zdarzenie wycofania rezerwacji

Interfejs API Wycofaj rezerwację służy jako operacja dla zdarzeń Rezerwacja. Umożliwia wycofanie zdarzenia rezerwacji określone przez reservationId lub zmniejszenie ilości rezerwacji.

Wycofanie jednego zdarzenia rezerwacji

Podczas tworzenia rezerwacji, identyfikator reservationId zostanie uwzględniony w treści odpowiedzi. Musisz podać taki sam reservationId, aby anulować rezerwację, i uwzględnić ten sam organizationId, productIdi dimensions użyte w wywołaniu interfejsu API rezerwacji. Na koniec należy określić wartość OffsetQty reprezentującą liczbę towarów, które mają zostać zwolnione z poprzedniej rezerwacji. Rezerwację można w całości lub częściowo wycofać w zależności od podanej wartości OffsetQty. Jeśli na przykład zarezerwowano 100 jednostek towaru, można określić OffsetQty: 10, aby cofnąć rezerwację 10 z początkowo zarezerwowanej ilości.

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
    }

Poniższy kod pokazuje przykład treści zawartości.

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

Poniższy kod pokazuje przykład pomyślnej treści odpowiedzi.

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

Banknot

W treści odpowiedzi, jeśli OffsetQty jest mniejsze lub równe ilości rezerwacji, stan processingStatus będzie „powodzenie” i totalInvalidOffsetQtyByReservId będzie 0.

Jeśli OffsetQty jest większe niż zarezerwowana kwota, stan processingStatus będzie „partialSuccess” i totalInvalidOffsetQtyByReservId będzie różnicą między OffsetQty a zarezerwowaną kwotą.

Na przykład, jeśli rezerwacja ma ilość 10 i OffsetQty ma wartość 12, totalInvalidOffsetQtyByReservId będzie 2.

Wycofanie wielu zdarzeń rezerwacji

Ten interfejs API jest wersją masową interfejsu API jednego zdarzenia.

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
        }
        ...
    ]

Czyszczenie danych rezerwacji

Interfejs API wyczyść dane rezerwacji służy do czyszczenia historycznych danych rezerwacji. Treść powinna być listą źródeł danych. Jeśli lista jest pusta, wszystkie źródła danych zostaną wyczyszczone.

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

Zapytanie o dostępne zapasy

Użyj interfejsu API zapytania o dostępne zapasy do pobierania bieżących danych o dostępnych zapasach produktów. Możesz użyć tego interfejsu API, gdy musisz znać stany magazynowe, na przykład, gdy chcesz przejrzeć stany magazynowe produktów w swojej witrynie e-commerce lub gdy chcesz sprawdzić dostępność produktów w różnych regionach lub w pobliskich sklepach i magazynach. Interfejs API aktualnie obsługuje wykonywanie zapytań o maksymalnie 5000 pojedynczych towarów według wartości productID. W każdym zapytaniu można określić również kilka wartości siteID i locationID. Gdy reguła partycji danych jest ustawiona na wartość Według lokalizacji, maksymalny limit jest definiowany przez następujące równanie:

Wartość NumOf(SiteID) × NumOf(LocationID) <= 10 000.

Zapytanie przy użyciu metody POST

Kwerenda według interfejsu API wpisu jest dostępna w dwóch wersjach. W poniższej tabeli przedstawiono różnice.

Interfejs API w wersji 1.0 Interfejs API w wersji 2.0
Można utworzyć kwerendę tylko dla jednego identyfikatora organizacji. Można utworzyć kwerendę dla wielu identyfikatorów organizacji.
Można utworzyć kwerendę dla maksymalnie 10 000 kombinacji lokalizacji i magazynów. Można utworzyć kwerendę na więcej niż 10 000 kombinacji identyfikatorów organizacji, lokalizacji i magazynów. Wyniki można zwracać na wielu stronach.

W poniższych podsekcjach przedstawiono sposób używania każdej wersji interfejsu API.

Kwerenda według wpisu wersji 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,
    }

W treści tego żądania dimensionDataSource to opcjonalny parametr. Jeśli nie jest ustawiony, filters będą traktowane jako wymiary bazowe.

Parametr returnNegative określa, czy wyniki zawierają wartości ujemne.

Zapytanie danych przechowywanych według lokalizacji

Ta sekcja ma zastosowanie, gdy reguła partycji danych jest ustawiona na Według lokalizacji.

  • organizationId powinna być tablicą zawierającą dokładnie jedną wartość.
  • productId może zawierać jedną lub więcej wartości. Jeśli jest to pusta tablica, system zwróci wszystkie produkty z określonych witryn i lokalizacji. W takim przypadku siteId i locationId nie powinny być puste.
  • siteId i locationId używane do partycjonowania. Można określić więcej niż jedną wartość siteId i locationId w żądaniu kwerendy o dane na dane zamówienie. Jeśli obie tablice są puste, system zwróci wszystkie witryny i lokalizacje określonych produktów. W takim przypadku productId nie powinno być puste.

Zalecamy używanie parametru groupByValues w sposób zgodny z konfiguracją indeksu. Więcej informacji można znaleźć w temacie Konfiguracja indeksu dostępnych zapasów.

Dane zapytania przechowywane przez identyfikator produktu

Ta sekcja ma zastosowanie, gdy reguła partycji danych jest ustawiona na Według identyfikator produktu. W takim przypadku wymagane są dwa pola filters: organizationId, productId.

  • organizationId powinna być tablicą zawierającą dokładnie jedną wartość.
  • productId powinna być tablicą zawierającą przynajmniej jedną wartość.

W przeciwieństwie do przechowywania danych według lokalizacji, jeśli nie zostaną określone wartości dla siteId i locationId, informacje o zapasach dla każdego identyfikatora produktu będą agregowane we wszystkich lokalizacjach i/lub lokalizacjach.

Uwaga

Jeśli włączono harmonogram dostępnych zmian i dostępne funkcje (ATP), zapytanie może również zawierać parametr logiczny QueryATP, który kontroluje, czy wyniki zapytania zawierają informacje ATP. Aby uzyskać więcej informacji i przykładów, zobacz Widoczność zapasów — harmonogramy i zmiany dostępnych zapasów oraz dostępność zapasów.

W poniższym przykładzie pokazano zawartość przykładowej treści. Pokazuje, że można kwerendy dotyczące dostępnych zapasów z wielu lokalizacji (magazynów).

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

Poniższe przykłady pokazują sposób wykonywania zapytań dla wszystkich produktów w określonej witrynie i w określonej lokalizacji.

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

Kwerenda według wpisu interfejsu API w wersji 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

Format żądania dla wersji API 2.0 jest podobny do formatu wersji 1.0, ale obsługuje również dwa opcjonalne parametry: pageNumber pageSize i które pozwalają systemowi podzielić jeden duży wynik na kilka mniejszych dokumentów. Wyniki są sortowane według magazynów (locationId), a parametry służą do dzielenia wyników na strony:

  • pageSize Ustala liczbę magazynów (locationId wartości) zwracanych na każdej stronie.
  • pageNumber Ustala numer strony, która jest zwrócona.

Żądanie tego formatu zwraca dane dotyczące dostępnych zapasów , począwszy od numeru magazynu ({pageNumber} − 1) × {pageSize} i zawiera dane dla następnych {pageSize} magazynów.

Interfejs API w wersji 2.0 odpowiada na dokument, który korzysta z następującej struktury:

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

Gdy żądanie osiągnie ostatni magazyn (locationId), wartość nextLink jest pustym ciągiem.

Ponadto w wersji API 2.0 można określić więcej niż jeden identyfikator organizacji w żądaniu. W tym celu należy w filtrze organizationId dokumentu żądania uwzględnić listę identyfikatorów organizacji rozdzielanych przecinkami. Na przykład "organizationId": ["org1", "org2", "org3"].

Zapytanie przy użyciu metody 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]

Oto przykładowy adres URL GET. To żądanie GET jest dokładnie takie samo, jak przykładowe księgowanie przedstawione wcześniej.

/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

System nie obsługuje wykonywania zapytań magazynowych w wielu identyfikatorach organizacji za pomocą metody GET.

Dokładne zapytanie pod ręką

Dostępne dokładne zapytania przypominają zwykłe dostępne zapytania, ale umożliwiają określenie hierarchii mapowania między witryną a lokalizacją. Na przykład masz następujące dwie witryny:

  • Lokalizacja 1, która jest mapowana na lokalizację A
  • Lokalizacja 2, która jest mapowana na lokalizację B

W przypadku zwykłego dostępnego zapytania, jeśli podasz "siteId": ["1","2"] i "locationId": ["A","B"], funkcja Widoczność zasobów automatycznie wyśle zapytanie wynik dla następujących witryn i lokalizacji:

  • Ośrodek 1, lokalizacja A
  • Ośrodek 1, lokalizacja B
  • Ośrodek 2, lokalizacja A
  • Ośrodek 2, lokalizacja B

Jak widać, zwykłe dostępne zapytanie nie rozpoznaje, że lokalizacja A istnieje tylko w witrynie 1, a lokalizacja B istnieje tylko w witrynie 2. W związku z tym tworzy nadmiarowe kwerendy. Aby uwzględnić to mapowanie hierarchiczne, można użyć dostępnego dokładnego zapytania i określić mapowania lokalizacji w treści zapytania. W takim przypadku zostaną kwerendy i wyniki zostaną uzyskane tylko dla lokacji 1, lokalizacji A i lokalizacji 2, lokalizacji B.

Kwerenda dokładnych informacji o podpłacie na czas przy użyciu metody księgowania

Dokładne zapytanie o dostępne dane według wpisu interfejsu API jest dostępne w dwóch wersjach. W poniższej tabeli przedstawiono różnice.

Interfejs API w wersji 1.0 Interfejs API w wersji 2.0
Można utworzyć kwerendę tylko dla jednego identyfikatora organizacji. Można utworzyć kwerendę dla wielu identyfikatorów organizacji.

Dokładne zapytanie o dane o dostępnach umożliwia księguj interfejs API w wersji 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,
    }

W treści tego żądania dimensionDataSource to opcjonalny parametr. Jeśli nie jest ustawiony, dimensions w filters będą traktowane jako wymiary bazowe. Istnieją cztery wymagane pola dla elementu filters: organizationId, productId, dimensions i values.

  • Element organizationId powinien zawierać tylko jedną wartość, ale nadal jest tablicą.
  • Element productId może zawierać jedną lub więcej wartości. Jeśli jest to pusta tablica, zostaną zwrócone wszystkie produkty.
  • W tablicy dimensions są wymagane siteId i locationId, tylko i wyłącznie, jeśli reguła partycji danych jest ustawiona na Według lokalizacji. W takim przypadku mogą pojawiać się razem z innymi elementami w dowolnej kolejności.
  • values może zawierać co najmniej jeden odrębnych tu należy do wartości odpowiadających dimensions.

dimensions w filters będą automatycznie dodane do groupByValues.

Parametr returnNegative określa, czy wyniki zawierają wartości ujemne.

W poniższym przykładzie pokazano zawartość przykładowej treści.

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

Poniższe przykłady pokazują sposób wykonywania zapytań dla wszystkich produktów w wielu witrynach i lokalizacjach.

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

Dokładne zapytanie o dane o podaną wydajność według wpisu interfejsu API w wersji 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,
    }

Wersja interfejsu API 2.0 różni się od wersji 1.0 pod następującymi sposobami:

  • W filters tej sekcji pole keys jest teraz dostępne, a nie dimensions pole. To keys pole działa podobnie do pola dimensions w wersji 1.0, ale może teraz również dołączyć organizationId. Klucze można określać w dowolnej kolejności.
  • Ta filters sekcja nie obsługuje już organizationId tego pola. Zamiast tego można uwzględnić wśród organizationId keys wymiarów w polu ( keys: ["organizationId", "siteId", "locationId"]na przykład) values i zdefiniować wartości identyfikatorów organizacji na zgodnym stanowisku w polu (na przykład values: ["SCM_IV", "iv_contoso_site_1", "iv_contoso_location_1"]).

Inne pola są identyczne z interfejsem API w wersji 1.0.

Zapytanie w wyszukiwarce produktów

Następujące interfejsy API zapytań o dostępne zapasy zostały ulepszone w celu obsługi wyszukiwania produktów:

Banknot

Kiedy publikujesz zapytanie dotyczące widoczności zapasów, które korzysta z wyszukiwania produktów, użyj parametru żądania productSearch (z obiektem ProductAttributeQuery w środku), aby znaleźć lub filtrować według identyfikatora produktu. Nowsze interfejsy API nie obsługują już starszego parametru żądania productid w treści żądania.

Wymagania wstępne

Aby rozpocząć korzystanie interfejsów API wyszukiwania produktów, Twój system musi spełniać następujące wymagania:

Umowa dotycząca wyszukiwania produktów

Umowa dotycząca wyszukiwania produktów określa zasady komunikacji z interfejsami API wyszukiwania produktów. Zapewnia ustandaryzowany sposób opisu możliwości i zachowania funkcji wyszukiwania produktów. Dzięki temu użytkownicy mogą łatwiej zrozumieć, wchodzić w interakcję i tworzyć aplikacje korzystające z interfejsów API widoczności magazynu.

W poniższym przykładzie pokazano przykładową umowę.

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

W poniższej tabeli przedstawiono pola używane w umowie.

Identyfikator pola Opis
logicalOperator Możliwe wartości to And i Or. Użyj tego pola, aby połączyć wiele warunków lub warunków i filtrów podrzędnych. Zauważ, że subFilters to właściwie obiekt productFilter lub attributeFilter. Dlatego możesz mieć subFilters wewnątrz subFilters.
conditionOperator Możliwe wartości to IsExactly, IsNot, Contains, DoesNotContain, BeginsWith, IsOneOf, GreaterEqual, LessEqual i Between.
ProductFilter Użyj tego pola, aby filtrować produkty według informacji o produkcie. Możesz na przykład zmienić productName w umowie na Company, itemNumber, productSearchName, productType, productName, productDescription, inventoryUnitSymbol, salesUnitSymbol lub purchaseUnitSymbol, aby dopasować się do potrzeb biznesowych.
AttributeFilter Użyj tego pola, aby filtrować produkty według informacji o atrybucie.
attributeArea Możliwe wartości to ProductAttribute, DimensionAttribute i 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,
    }

W poniższym przykładzie pokazano zawartość przykładowej treści.

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

W poniższym przykładzie pokazano odpowiedź pomyślną.

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

W poniższym przykładzie pokazano zawartość przykładowej treści.

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

W poniższym przykładzie pokazano odpowiedź pomyślną.

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

Dostępność zapasów

Widoczność zapasów można skonfigurować, aby było można zaplanować przyszłe zmiany dostępnych zapasów i obliczyć ilości ATP. ATP to ilość towaru, która jest dostępna i którą można obiecać klientowi w następnym okresie. Użycie kalkulacji ATP może znacznie zwiększyć twoje możliwości realizacji zamówień. Aby uzyskać informacje o tym, jak włączyć tę funkcję i jak wchodzić w interakcję z widocznością zapasów za pośrednictwem interfejsu API po włączeniu tej funkcji, zobacz Harmonogramy zmian widoczności zapasów na bieżąco i dostępne do obiecania.

Alokacja

Interfejsy API związane z alokacją znajdują się w Przydział widoczności zapasów.