Teilen über

Inventory Visibility öffentliche APIs

  • Artikel

Hinweis

Azure Active Directory ist jetzt Microsoft Entra ID. Mehr erfahren

Dieser Artikel beschreibt die öffentlichen APIs, die von Inventory Visibility bereitgestellt werden.

Die öffentliche REST-API des Bestandssichtbarkeit-Add-Ins stellt mehrere spezifische Endpunkte für die Integration bereit. Es werden vier Hauptinteraktionstypen unterstützt:

  • Verbuchung von Änderungen des Lagerbestands aus einem externen System in das Add-In
  • Festlegen oder Außerkraftsetzen von Lagerbestandsmengen im Add-In von einem externen System
  • Buchen von Reservierungsereignissen an das Add-In von einem externen System
  • Abfrage aktueller Lagerbestände von einem externen System

In der folgenden Tabelle sind die derzeit verfügbaren APIs aufgeführt:

Pfad Methode Beschreibung
/api/environment/{environmentId}/onhand Posten Ein Ereignis zur Änderung des Lagerbestands erstellen
/api/environment/{environmentId}/onhand/bulk Posten Mehrere Änderungsereignisse erstellen
/api/environment/{environmentId}/setonhand/{inventorySystem}/bulk Posten Festlegen/Überschreiben von Lagerbeständen
/api/environment/{environmentId}/onhand/reserve Posten Ein Ereignis für eine Soft-Reservierung erstellen
/api/environment/{environmentId}/onhand/reserve/bulk Posten Mehrere Soft-Reservierungsereignisse erstellen
/api/environment/{environmentId}/onhand/unreserve Posten Ein Soft-Reservierungsereignis umkehren
/api/environment/{environmentId}/onhand/unreserve/bulk Posten Mehrere Soft-Reservierungsereignisse umkehren
/api/environment/{environmentId}/onhand/reserve/resyncjob Posten Reservierungsdaten bereinigen
/api/environment/{environmentId}/onhand/changeschedule Posten Eine geplante Änderung des Lagerbestands erstellen
/api/environment/{environmentId}/onhand/changeschedule/bulk Posten Erstellen Sie mehrere Lagerbestandsänderungen mit Daten
/api/environment/{environmentId}/onhand/indexquery Posten Abfrage durch Verwendung der Methode POST (empfohlen)
/api/environment/{environmentId}/onhand Abrufen Abfrage mit Hilfe der get-Methode
/api/environment/{environmentId}/onhand/exactquery Posten Exakte Abfrage durch Verwendung der Methode POST
/api/environment/{environmentId}/allocation/allocate Posten Ein Zuweisungsereignis erstellen
/api/environment/{environmentId}/allocation/unallocate Posten Ein Ereignis zum Aufheben einer Zuweisung erstellen
/api/environment/{environmentId}/allocation/reallocate Posten Ein Neuzuweisungsereignis erstellen
/api/environment/{environmentId}/allocation/consume Posten Ein Verbrauchsereignis erstellen
/api/environment/{environmentId}/allocation/query Posten Zuordnungsergebnis abfragen
/api/environment/{environmentId}/onhand/productsearch/indexquery Posten Indexabfrage mit Produktsuche veröffentlichen
/api/environment/{environmentId}/onhand/productsearch/exactquery Posten Genaue Abfrage mit Produktsuche veröffentlichen

Hinweis

Der Teil {environmentId} des Pfades ist die Umgebungs-ID in Microsoft Dynamics Lifecycle Services.

Die Bulk-API kann maximal 512 Datensätze für jede Anfrage zurückgeben.

Authentifizierung

Das Sicherheits-Token der Plattform wird für den Aufruf der öffentlichen API von Inventory Visibility verwendet. Daher müssen Sie ein Microsoft Entra-Token generieren, indem Sie Ihre Microsoft Entra-Anwendung verwenden. Sie müssen dann das Microsoft Entra-Token verwenden, um das Zugriffstoken vom Sicherheitsdienst zu erhalten.

Gehen Sie folgendermaßen vor, um ein Sicherheitsdienst-Token zu erhalten.

  1. Melden Sie sich am Azure-Portal an und suchen Sie dort die clientId- und clientSecret-Werte für Ihre Dynamics 365 Supply Chain Management-App.

  2. Holen Sie einen Microsoft Entra-Token (aadToken), indem Sie eine HTTP-Anforderung senden, die die folgenden Eigenschaften hat:

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

    • Methode:GET

    • Body-Inhalt (Formulardaten):

      Schlüssel Wert
      client_id ${aadAppId}
      client_secret ${aadAppSecret}
      grant_type client_credentials
      Bereich 0cdb527f-a8d1-4bf8-9436-b352c68682b2/.default

    Sie sollten als Antwort ein Microsoft Entra-Token (aadToken) erhalten. Es sollte dem folgenden Beispiel ähneln.

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

  3. Formulieren Sie eine Anfrage in JavaScript Object Notation (JSON), die dem folgenden Beispiel ähnelt.

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

    Beachten Sie die folgenden Punkte:

    • Der client_assertion-Wert muss das Microsoft Entra-Token (aadToken) sein, das Sie im vorherigen Schritt erhalten haben.
    • Der Wert von context muss die Lifecycle Services Umgebungs-ID sein, unter der Sie das Add-In bereitstellen möchten.
    • Legen Sie alle anderen Werte fest, wie im Beispiel gezeigt.

  4. Rufen Sie einen Zugriffstoken (access_token) ab, indem Sie eine HTTP-Anforderung mit den folgenden Eigenschaften senden:

    • URL:https://securityservice.operations365.dynamics.com/token
    • Methode:POST
    • HTTP-Header: Geben Sie die API-Version an. (Der Schlüssel ist Api-Version, und der Wert ist 1.0.)
    • Body-Inhalt: Fügen Sie die JSON-Anfrage ein, die Sie im vorherigen Schritt erstellt haben.

    Sie sollten als Antwort ein Zugriffs-Token (access_token) erhalten. Sie müssen dieses Token als Träger-Token verwenden, um die Inventory Visibility API aufzurufen. Hier ist ein Beispiel.

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

Schein

Die URL https://securityservice.operations365.dynamics.com/token ist eine allgemeine URL für den Sicherheitsdienst. Wenn Sie die URL aufrufen, ist die erste Antwort eine HTTP-Umeiltungsantwort mit dem Statuscode 307 in den Antwortheadern und einem Eintrag mit dem Schlüssel „Standort“, der die Ziel-URL für den Sicherheitsdienst enthält. Die URL hat dieses Format: https://gw.{$geo}-il101.gateway.prod.island.powerapps.com/securityservice/token. Beispiel: wenn sich Ihre Umgebung im geografischen US-Raum befindet, könnte die URL https://gw.us-il101.gateway.prod.island.powerapps.com/securityservice/token sein. Wenn der 307-Antwortstatuscode nicht für Sie gilt, können Sie die tatsächliche URL gemäß des Standorts Ihrer FinOps-Umgebung konstruieren. Am einfachsten ist es, https://gw.as-il101.gateway.prod.island.powerapps.com/securityservice/token mit Ihrem Webbrowser zu öffnen und die Adresse in die Adressleiste zu kopieren.

Erstellen von Ereignissen bei Lagerbestandsänderungen

Es gibt zwei APIs zum Erstellen von Ereignissen zur Änderung des Lagerbestands:

  • Erzeugen eines Datensatzes: /api/environment/{environmentId}/onhand
  • Mehrere Datensätze erstellen: /api/environment/{environmentId}/onhand/bulk

Die folgende Tabelle fasst die Bedeutung der einzelnen Felder im JSON-Körper zusammen.

Feldkennung Description
id Eine eindeutige ID für das spezifische Änderungsereignis. Bei einer erneuten Übermittlung aufgrund eines Systemfehlers wird diese ID verwendet, um sicherzustellen, dass dasselbe Ereignis im System nicht doppelt gezählt wird.
organizationId Die Kennung der Organisation, die mit dem Ereignis verknüpft ist. Dieser Wert wird einer Organisations- oder Datenbereichskennung im Supply Chain Management zugeordnet.
productId Die Kennung des Produkts.
quantities Die Menge, um die der Lagerbestand geändert werden muss. Wenn z.B. 10 neue Bücher zu einem Regal hinzugefügt werden, ist dieser Wert quantities:{ shelf:{ received: 10 }}. Wenn drei Bücher aus dem Regal entfernt oder verkauft werden, ist dieser Wert quantities:{ shelf:{ sold: 3 }}.
dimensionDataSource Die Datenquelle der Dimensionen, die im Buchungsänderungsereignis und in der Abfrage verwendet werden. Wenn Sie die Datenquelle angeben, können Sie die benutzerdefinierten Dimensionen aus der angegebenen Datenquelle verwenden. Inventory Visibility kann die Dimensionskonfiguration verwenden, um die angepassten Dimensionen den allgemeinen Standarddimensionen zuzuordnen. Wenn kein dimensionDataSource-Wert angegeben wird, können Sie nur die allgemeinen Basisdimensionen in Ihren Abfragen verwenden.
dimensions Ein dynamisches Schlüssel-Werte-Paar. Die Werte werden einigen der Dimensionen im Supply Chain Management zugeordnet. Sie können jedoch auch angepasste Dimensionen hinzufügen (z. B. Quelle), um anzugeben, ob das Ereignis aus dem Supply Chain Management oder einem externen System stammt.

Hinweis

Wenn Ihre Datenpartitionsregel auf Nach Produkt-ID eingestellt ist, sind siteId und locationId optionale Dimensionen. Andernfalls handelt es sich um erforderliche Abmessungen. Diese Regel gilt auch für die APIs für Zuweisung, unverbindliche Reservierung und Änderungszeitplan.

Die folgenden Unterabschnitte enthalten Beispiele, die zeigen, wie diese APIs verwendet werden.

Ein Ereignis zur Änderung des Lagerbestands erstellen

Diese API erstellt ein einzelnes Ereignis zur Änderung des Lagerbestands.

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

Das folgende Beispiel zeigt einen Beispielkörperinhalt. In diesem Beispiel verfügt das Unternehmen über ein Point-of-Sale-System (POS), das Transaktionen im Geschäft und damit Bestandsänderungen verarbeitet. Der Kunde hat ein rotes T-Shirt in Ihrem Geschäft zurückgegeben. Um die Änderung widerzuspiegeln, buchen Sie ein einziges Änderungsereignis für das Produkt T-Shirt. Dieses Ereignis erhöht die Menge des Produkts T-Shirt um 1.

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

Das folgende Beispiel zeigt einen Beispielkörperinhalt ohne dimensionDataSource. In diesem Fall sind dimensions die Basisdimensionen. Wenn dimensionDataSource festgelegt ist, können dimensions entweder die Datenquellendimensionen oder die Basisdimensionen sein.

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

Mehrere Änderungsereignisse erstellen

Diese API kann Änderungsereignisse erstellen, genau wie die Single-Event-API kann. Der einzige Unterschied besteht darin, dass diese API mehrere Datensätze gleichzeitig erstellen kann. Deshalb, unterscheiden sich die Path und Body Werte. Bei dieser API liefert Body ein Array von Datensätzen. Die maximale Anzahl an Datensätzen ist 512. Daher kann die Bulk-API für Lagerbestandsänderungen bis zu 512 Änderungsereignisse gleichzeitig unterstützen.

Ein POS-Gerät in einem Einzelhandelsgeschäft verarbeitete beispielsweise die folgenden zwei Transaktionen:

  • Eine Rücksendung von einem roten T-Shirt
  • Eine Verkaufstransaktion von drei schwarzen T-Shirts

In diesem Fall können Sie beide Bestandsaktualisierungen in einen API-Aufruf einbeziehen.

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

Das folgende Beispiel zeigt einen Beispielkörperinhalt.

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

Lagerbestände festlegen/überschreiben

Die Setzen von Lagerbeständen API setzt die aktuellen Daten für das angegebene Produkt außer Kraft. Diese Funktion wird normalerweise verwendet, um Bestandszählungsaktualisierungen durchzuführen. Beispielsweise könnte ein Geschäft während seiner täglichen Bestandszählung feststellen, dass der tatsächliche Lagerbestand für ein rotes T-Shirt 100 beträgt. Daher muss die POS-Eingangsmenge unabhängig von der vorherigen Menge auf 100 aktualisiert werden. Sie können diese API verwenden, um den vorhandenen Wert zu überschreiben.

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

Das folgende Beispiel zeigt einen Beispielkörperinhalt. Das Verhalten dieser API unterscheidet sich vom Verhalten der APIs, die im Abschnitt Erstellen von Ereignissen zur Änderung des Lagerbestands weiter oben in diesem Artikel beschrieben sind. In diesem Beispiel wird die Menge des Produkts T-Shirt auf 1 festgelegt.

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

Erstellen von Reservierungsereignissen

Um die Reserve-API zu verwenden, müssen Sie die Funktion „Reservierung“ öffnen und die Konfiguration der Reservierung abschließen. Weitere Informationen (einschließlich eines Dataflows und eines Beispielszenarios) finden Sie unter Bestandsanzeige-Reservierungen.

Erstellen Sie ein Ereignis für die Reservierung

Eine Reservierung kann für verschiedene Datenquelleneinstellungen vorgenommen werden. Um diese Art der Reservierung zu konfigurieren, geben Sie zuerst die Datenquelle im dimensionDataSource-Parameter an. Geben Sie dann im dimensions-Parameter die Dimensionen gemäß den Dimensionseinstellungen in der Zieldatenquelle an.

Wenn Sie die Reservierungs-API aufrufen, können Sie die Reservierungsvalidierung steuern, indem Sie den booleschen ifCheckAvailForReserv-Parameter im Anforderungstext angeben. Der Wert True bedeutet, dass die Validierung erforderlich ist, während der Wert False bedeutet, dass die Validierung nicht erforderlich ist. Der Standardwert ist True.

Wenn Sie eine Reservierung umkehren oder die Reservierung bestimmter Bestandsmengen aufheben möchten, setzen Sie die Menge auf einen negativen Wert und legen Sie den ifCheckAvailForReserv-Parameter auf False fest, um die Validierung zu überprüfen. Es gibt auch eine dedizierte API zum Aufheben der Reservierung, um dasselbe zu tun. Der Unterschied besteht nur in der Art und Weise, wie die beiden APIs aufgerufen werden. Es ist einfacher, ein bestimmtes Reservierungsereignis mithilfe der reservationId mit der Reservierung aufheben API umzukehren. Weitere Informationen finden Sie im Abschnitt Ein Reservierungsereignis aufheben.

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

Das folgende Beispiel zeigt einen Beispielkörperinhalt.

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

Das folgende Beispiel zeigt eine erfolgreiche Antwort.

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

Erstellen Sie mehrere Reservierungsereignisse

Diese API ist eine Massenversion der Einzelereignis-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,
        },
        ...
    ]

Reservierungsereignisse umkehren

Die Reservierung aufheben API dient als Umkehrvorgang für Reservierungsereignisse. Sie bietet eine Möglichkeit, ein durch reservationId spezifiziertes Reservierungsereignis umzukehren oder die Reservierungsmenge zu verringern.

Ein Reservierungsereignis umkehren

Wenn eine Reservierung erstellt wird, wird in den Antworttext eine reservationId aufgenommen. Sie müssen dieselbe reservationId bereitstellen, um die Reservierung zu stornieren, und dieselbe organizationId, productId und dimensions einfügen, die für den Aufruf der Reservierungs-API verwendet wird. Geben Sie abschließend einen Wert für OffsetQty an, der die Anzahl der Artikel darstellt, die aus der vorherigen Reservierung freigegeben werden sollen. Je nach der angegebenen OffsetQty, kann eine Reservierung vollständig oder teilweise umgekehrt werden. Wenn zum Beispiel 100 Einheiten von Artikeln reserviert wurden, können Sie OffsetQty: 10 auf 10 der ursprünglich reservierten Menge festlegen.

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
    }

Der folgende Code zeigt einen Beispiel für einen Antwortinhalt.

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

Der folgende Code zeigt einen Beispiel für einen erfolgreichen Antworttext.

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

Notiz

Wenn im Antworttext OffsetQty kleiner oder gleich der Reservierungsmenge ist, ist der processingStatus auf Erfolg und die totalInvalidOffsetQtyByReservId auf 0 gestellt.

Wenn die OffsetQty größer als die reservierte Menge ist, lautet der processingStatus partialSuccess und totalInvalidOffsetQtyByReservId zeigt die Differenz zwischen OffsetQty und der reservierten Menge an.

Wenn die Reservierung beispielsweise eine Menge von 10 und OffsetQty einen Wert von 12 hat, ist totalInvalidOffsetQtyByReservId 2.

Mehrere Reservierungsereignisse umkehren

Diese API ist eine Massenversion der Einzelereignis-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
        }
        ...
    ]

Reservierungsdaten bereinigen

Die API Reservierungsdaten bereinigen wird zum Bereinigen historischer Reservierungsdaten verwendet. Der Hauptteil sollte eine Liste von Datenquellen sein. Wenn die Liste leer ist, werden alle Datenquellen bereinigt.

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

Lagerbestand abfragen

Verwenden Sie die Abfrage des Lagerbestands API, um aktuelle Daten zum Lagerbestand Ihrer Produkte abzurufen. Sie können diese API immer dann verwenden, wenn Sie den Lagerbestand kennen müssen, z. B. wenn Sie die Produktlagerbestände auf Ihrer E-Commerce-Website überprüfen möchten oder wenn Sie die Produktverfügbarkeit in verschiedenen Regionen oder in nahe gelegenen Geschäften und Lagern überprüfen möchten. Die API unterstützt derzeit die Abfrage von bis zu 5000 einzelnen Elementen nach dem productID-Wert. In jeder Abfrage können auch mehrere siteID- und locationID-Werte angegeben werden. Wenn Ihre Datenpartitionsregel auf Nach Standort eingestellt ist, wird die Höchstgrenze durch die folgende Gleichung definiert:

Anzahl(SiteID) × Anzahl(LocationID) <= 10.000.

Abfrage mit Hilfe der POST-Methode

Die Query-by-Post-API ist in zwei Versionen verfügbar. In der folgenden Tabelle sind die Unterschiede aufgeführt.

API-Version 1.0 API-Version 2.0
Kann nur eine Organisations-ID abfragen. Kann mehrere Organisations-IDs abfragen.
Bis zu 10.000 Standort- und Lagerkombinationen können abgefragt werden. Kann mehr als 10.000 Kombinationen aus Organisations-IDs, Standorten und Lagern abfragen. Kann Ergebnisse auf mehreren Seiten zurückgeben.

Die folgenden Unterabschnitte zeigen, wie jede API-Version verwendet wird.

Abfrage per Post-API Version 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,
    }

Im Body-Teil dieser Anfrage ist dimensionDataSource ein optionaler Parameter. Wenn er nicht festgelegt ist, wird filters als Basisdimensionen behandelt.

Der returnNegative-Parameter steuert, ob die Ergebnisse negative Einträge enthalten.

Abfragen von nach Standort gespeicherten Daten

Dieser Abschnitt gilt, wenn Ihre Datenpartitionsregel auf Nach Standort eingestellt ist.

  • organizationId sollte ein Array sein, das genau einen Wert enthält.
  • productId kann einen oder mehrere Werte enthalten. Wenn es sich um ein leeres Array handelt, gibt das System alle Produkte für die spezifischen Websites und Standorte zurück. In diesem Fall sollten siteId und locationId nicht leer sein.
  • siteId und locationId werden zur Partitionierung verwendet. Sie in einer Lagerbestand abfragen-Anforderung mehr als einen Wert für siteId und locationId angeben. Wenn beide Arrays leer sind, gibt das System alle Websites und Standorte für die spezifischen Produkte zurück. In diesem Fall sollte productId nicht leer sein.

Wir empfehlen, den Parameter groupByValues so zu verwenden, dass er mit Ihrer Indexkonfiguration übereinstimmt. Weitere Informationen finden Sie unter Indexkonfiguration des verfügbaren Lagerbestands.

Nach Produkt-ID gespeicherte Daten abfragen

Dieser Abschnitt gilt, wenn Ihre Datenpartitionsregel auf Nach Produkt-ID eingestellt ist. In diesem Fall sind zwei filters-Felder erforderlich: organizationId, productId.

  • organizationId sollte ein Array sein, das genau einen Wert enthält.
  • productId sollte ein Array sein mit mindestens einem Wert.

Wenn Sie, anders als beim Speichern der Daten nach Standort, für siteId und locationId keine Werte angeben, werden die Bestandsinformationen für jede Produkt-ID über alle Sites und/oder Standorte hinweg aggregiert.

Hinweis

Wenn Sie die Funktionen Lagerbestand und ATP (Available-to-Promise) aktiviert haben, kann Ihre Abfrage auch den booleschen Parameter QueryATP enthalten, der steuert, ob die Abfrageergebnisse ATP-Informationen enthalten. Weitere Informationen und Beispiele finden Sie unter Inventory Visibility Lagerbestands-Änderungstermine und verfügbares Versprechen.

Das folgende Beispiel zeigt einen Beispielkörperinhalt. Es zeigt, dass Sie den verfügbaren Bestand von mehreren Standorten (Lagern) aus abfragen können.

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

Das folgende Beispiel zeigt, wie Sie alle Produkte an einem bestimmten Standort und Lagerplatz abfragen.

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

Abfrage per Post-API Version 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

Das Anforderungsformat für API-Version 2.0 ähnelt dem der Version 1.0, unterstützt jedoch auch zwei optionale Parameter: pageNumber und pageSize, die es dem System ermöglichen, ein einzelnes großes Ergebnis in mehrere kleinere Dokumente aufzuteilen. Die Ergebnisse werden nach Lager (locationId) sortiert und die Parameter werden wie folgt verwendet, um die Ergebnisse auf Seiten aufzuteilen:

  • pageSize Legt die Anzahl der Lager (locationId Werte) fest, die auf jeder Seite zurückgegeben werden.
  • pageNumber legt die zurückgegebene Seitenzahl fest.

Eine Anfrage dieses Formats gibt Daten zum verfügbaren Lagerbestand zurück, beginnend mit der Lagernummer ({pageNumber} − 1) × {pageSize} , und schließt Daten für die nächsten {pageSize} Lager ein.

API-Version 2.0 antwortet mit einem Dokument, das die folgende Struktur verwendet:

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

Wenn die Anfrage das letzte Lager (locationId) erreicht, ist der nextLink Wert eine leere Zeichenfolge.

Mit der API-Version 2.0 können Sie in Ihrer Anfrage auch mehr als eine Organisations-ID angeben. Fügen Sie dazu eine durch Kommas getrennte Liste von Organisations-IDs in den organizationId Filter Ihres Anforderungsdokuments ein. Beispiel: "organizationId": ["org1", "org2", "org3"].

Abfrage mit Hilfe der get-Methode

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]

Hier ist eine Beispiel-GET-URL. Diese get-Anfrage ist genau die gleiche wie das post-Beispiel, das zuvor bereitgestellt wurde.

/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

Das System unterstützt keine Bestandsabfrage über mehrere Organisations-IDs mit der GET-Methode.

Exakte Bestandsabfrage

Exakt verfügbare Abfragen ähneln normalen verfügbaren Abfragen, aber sie ermöglichen es Ihnen, eine Zuordnungshierarchie zwischen einem Standort und einem Standort anzugeben. Sie haben zum Beispiel die folgenden zwei Websites:

  • Standort 1, der Standort A zugeordnet ist
  • Standort 2, der Standort B zugeordnet ist

Für eine regelmäßige Verfügbarkeitsabfrage, wenn Sie "siteId": ["1","2"] und "locationId": ["A","B"] angeben, fragt Bestandsanzeige automatisch das Ergebnis für die folgenden Sites und Standorte ab:

  • Standort 1, Lagerplatz A
  • Standort 1, Lagerplatz B
  • Standort 2, Lagerplatz A
  • Standort 2, Lagerplatz B

Wie Sie sehen, erkennt die normale Verfügbarkeitsabfrage nicht, dass Standort A nur an Standort 1 und Standort B nur an Standort 2 vorhanden ist. Daher macht es redundante Abfragen. Um diese hierarchische Zuordnung zu berücksichtigen, können Sie eine verfügbare exakte Abfrage verwenden und die Standortzuordnungen im Abfragetext angeben. In diesem Fall werden Sie nur Ergebnisse für Website 1, Standort A und Website 2, Standort B abfragen und erhalten.

Vorrätige exakte Abfrageabfrage mit der Post-Methode

Die API zur Bestandsgenauen Abfrage per Post ist in zwei Versionen verfügbar. In der folgenden Tabelle sind die Unterschiede aufgeführt.

API-Version 1.0 API-Version 2.0
Kann nur eine Organisations-ID abfragen. Kann mehrere Organisations-IDs abfragen.

Genaue Bestandsabfrage per Post-API Version 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,
    }

Im Body-Teil dieser Anfrage ist dimensionDataSource ein optionaler Parameter. Wenn er nicht festgelegt ist, wird dimensions in filters als Basis Dimensionen behandelt. Es gibt vier Pflichtfelder für filters: organizationId, productId, dimensions und values.

  • organizationId sollte nur einen Wert enthalten, ist jedoch nach wie vor ein Array.
  • productId könnte einen oder mehrere Werte enthalten. Wenn es sich um ein leeres Array handelt, werden alle Produkte zurückgegeben.
  • Im dimensions-Array sind siteId und locationId nur dann erforderlich, wenn Ihre Datenpartitionsregel auf Nach Standort eingestellt ist. In diesem Fall könnten sie mit anderen Elementen in beliebiger Reihenfolge erscheinen.
  • values kann ein oder mehrere unterschiedliche Tupel von Werten enthalten, die dimensions entsprechen.

dimensions in filters wird automatisch zu groupByValues hinzugefügt.

Der returnNegative-Parameter steuert, ob die Ergebnisse negative Einträge enthalten.

Das folgende Beispiel zeigt einen Beispielkörperinhalt.

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

Das folgende Beispiel zeigt, wie Sie alle Produkte in mehreren Betrieben und Standorten abfragen können.

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

Lagerbestandsgenaue Abfrage per Post-API Version 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-Version 2.0 unterscheidet sich von Version 1.0 in folgenden Punkten:

  • Der filters Abschnitt hat jetzt ein keys Feld statt einem dimensions Feld. Das Feld keys funktioniert wie das Feld dimensions in Version 1.0, kann jetzt aber auch organizationId enthalten. Sie können die Schlüssel in beliebiger Reihenfolge angeben.
  • Der filters Abschnitt unterstützt das organizationId Feld nicht mehr. Stattdessen können Sie organizationId zu den Dimensionen im keys Feld zählen (z. B. keys: ["organizationId", "siteId", "locationId"]) und Organisations-ID-Werte an der entsprechenden Position im values Feld definieren (z. B. values: ["SCM_IV", "iv_contoso_site_1", "iv_contoso_location_1"]).

Andere Felder sind identisch mit API-Version 1.0.

Abfrage mit Produktsuche

Die folgenden verfügbaren Abfrage-APIs wurden erweitert, um die Produktsuche zu unterstützen:

Schein

Wenn Sie eine Abfrage zur Bestandssichtbarkeit veröffentlichen, die die Produktsuche verwendet, verwenden Sie die productSearch-Anfrageparameter (mit einem ProductAttributeQuery-Objekt darin), um die Produkt-ID zu finden oder nach ihr zu filtern. Die neueren APIs unterstützen die älteren productid-Anforderungsparameter im Anforderungstext nicht mehr.

Voraussetzungen

Bevor Sie mit der Nutzung der Produktsuch-APIs beginnen können, muss Ihr System die folgenden Anforderungen erfüllen:

Vertrag zur Produktsuche

Der Vertrag zur Produktsuche definiert die Regeln für die Kommunikation mit den Produktsuch-APIs. Er bietet eine standardisierte Möglichkeit, die Funktionen und das Verhalten der Produktsuchfunktionen zu beschreiben. Daher können Benutzende Anwendungen, die die Bestandsanzeige-APIs nutzen, leichter verstehen, mit ihnen interagieren und erstellen.

Das folgende Beispiel zeigt einen Beispielvertrag.

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

In der folgenden Tabelle werden die Felder beschrieben, die im Vertrag verwendet werden.

Feldkennung Beschreibung
logicalOperator Die möglichen Werte sind And und Or. Verwenden Sie dieses Feld, um mehrere Bedingungen oder Bedingungen und Unterfilter zu verbinden. Beachten Sie, dass subFilters eigentlich ein productFilter- oder ein attributeFilter-Objekt ist. Deshalb können Sie subFilters innerhalb von subFilters haben.
conditionOperator Die möglichen Werte sind IsExactly, IsNot, Contains, DoesNotContain, BeginsWith, IsOneOf, GreaterEqual, LessEqual und Between.
ProductFilter Verwenden Sie dieses Feld, um Produkte nach produktbezogenen Informationen zu filtern. Sie können zum Beispiel productName im Vertrag mit Company, itemNumber, productSearchName, productType, productName, productDescription, inventoryUnitSymbol, salesUnitSymbol oder purchaseUnitSymbol passend zu Ihren Geschäftsanforderungen ändern.
AttributeFilter Verwenden Sie dieses Feld, um Produkte nach attributbezogenen Informationen zu filtern.
attributeArea Die möglichen Werte sind ProductAttribute, DimensionAttribute und 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,
    }

Das folgende Beispiel zeigt einen Beispielkörperinhalt.

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

Das folgende Beispiel zeigt eine erfolgreiche Antwort.

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

Das folgende Beispiel zeigt einen Beispielkörperinhalt.

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

Das folgende Beispiel zeigt eine erfolgreiche Antwort.

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

Verfügbar für Zusage

Sie können Inventory Visibility so festlegen, dass Sie zukünftige Änderungen des Lagerbestands planen und ATP-Mengen berechnen können. VfZ ist die Menge eines Elements, die verfügbar ist und einem Kunden bzw. einer Kundin in der nächsten Periode zugesagt werden kann. Die Verwendung der ATP-Berechnung kann Ihre Funktionalitäten bei der Auftragsabwicklung erheblich steigern. Informationen darüber, wie Sie diese Funktion aktivieren und wie Sie mit Inventory Visibility über die API interagieren können, nachdem die Funktion aktiviert wurde, finden Sie unter Inventory Visibility Lagerbestand ändert Zeitpläne und ist für Versprechen verfügbar.

Zuweisung

Zuweisungsbezogene APIs befinden sich in Zuweisung der Bestandsichtbarkeit.