Orders Lesen

pixiOrderGetByTags

Liefert Aufträge eines Datumsbereichs, gefiltert nach Auftrags-Tags mit AND-, OR- und NOT-Bedingungen aus einem XML-Filter.

Sucht Aufträge anhand der zugeordneten Tags. Der Filter wird als XML in TagFilter übergeben.

Auswertung und Prüfung

Das XML wird unter /TagFilter/AND, /TagFilter/OR und /TagFilter/NOT gelesen. Jeder Block kann beliebig viele TagId- und TagName-Elemente enthalten. Tag-Namen werden getrimmt, leere Namen werden ignoriert.
Jeder Eintrag wird gegen die Tags vom Typ 2 (Auftrags-Tags) aufgelöst:
- über Id, wenn TagId angegeben ist;
- über den exakten Name bei PartialTagNameMatch = 0;
- über Name LIKE '%…%' bei PartialTagNameMatch = 1.
Ein Teiltreffer kann einen Eintrag auf mehrere Tags auflösen.
Ein Eintrag ohne passenden Tag erhält den Status ERROR.
Ein Tag, der in der aufgelösten Liste mehrfach vorkommt, erhält ebenfalls ERROR. Das gilt operationsübergreifend und auch innerhalb derselben Operation, z. B. bei Angabe per Id und per Name.
Hat ein Eintrag einen Fehler, liefert der Aufruf die vollständige Prüfliste (eine Zeile je aufgelöstem Eintrag) und keine Aufträge.
Ist das XML nicht lesbar (oder eine TagId nicht numerisch), wird eine einzelne Fehlerzeile geliefert.

Auftragssuche (nur bei erfolgreicher Prüfung)

DateFrom ist standardmäßig 6 Monate vor jetzt, DateTo jetzt und RowCount 1000.
Der Datumsbereich wird in einen Schlüsselbereich umgerechnet. Er beginnt beim kleinsten OrderHeaderKey mit OrderDate >= DateFrom und endet beim größten OrderHeaderKey mit OrderDate < DateTo. Alle Aufträge mit einem Schlüssel in diesem Bereich werden berücksichtigt.
NOT: Der Auftrag darf keinen der NOT-Tags tragen.
OR: Der Auftrag muss mindestens einen der OR-Tags tragen.
AND: Der Auftrag muss alle AND-Tags tragen.
Leere Blöcke werden nicht angewendet. Enthält der Filter keine Tags (oder ist TagFilter leer), werden alle Aufträge des Bereichs geliefert.
Das Ergebnis wird auf TOP (RowCount) begrenzt und nach OrderHeaderKey aufsteigend sortiert.

Hinweise

Alle Lesezugriffe verwenden NOLOCK, es können also nicht festgeschriebene Daten geliefert werden.
StrictANDCondition ist als obsolet markiert und wird nicht verwendet.
Der Datumsfilter wirkt über den Schlüsselbereich, nicht direkt über OrderDate. Aufträge mit einem Schlüssel im Bereich, deren Datum außerhalb liegt, werden trotzdem geliefert.
DateTo ist exklusiv.
Gibt es zu einer Datumsgrenze keinen Auftrag, ist der Schlüsselbereich leer und es werden keine Zeilen geliefert.
Die AND-Prüfung vergleicht die Anzahl passender Tag-Zuordnungen mit der Anzahl der AND-Tags. Doppelte Zuordnungen desselben Tags zu einem Auftrag können das Ergebnis verfälschen.
Bei PartialTagNameMatch = 1 zählt jeder über das Namensmuster gefundene Tag als eigener Tag. Bei AND sind damit alle gefundenen Tags erforderlich.
Ein Code-Kommentar weist darauf hin, dass die OR-Bedingung möglicherweise nicht korrekt funktioniert.
Die Meldung Tag used in another operation wird auch gesetzt, wenn derselbe Tag innerhalb einer Operation doppelt referenziert wird.
Beide möglichen ersten Ergebnismengen kommen als SqlRowSet1 an. Zur Unterscheidung von Prüfliste und Auftragsliste auf die Spalte Status prüfen.
Ein negativer RowCount löst einen SQL-Fehler außerhalb der Fehlerbehandlung aus.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`TagFilter` Pflicht	varchar(max) xml	–	XML-Filter mit `AND`-, `OR`- und `NOT`-Blöcken unter `TagFilter`, jeweils mit `TagId`- und/oder `TagName`-Elementen. Ein leerer Wert bedeutet keinen Tag-Filter. Beispiel: `<TagFilter> <AND> <TagId>12</TagId> <TagName>Express</TagName> </AND> <OR> <TagId>15</TagId> <TagName>Marketplace</TagName> </OR> <NOT> <TagId>7</TagId> <TagName>Blocked</TagName> </NOT> </TagFilter>`
`PartialTagNameMatch`	bit boolean	0	Steuert, wie `TagName`-Einträge abgeglichen werden. Erlaubte Werte `0` – Tag-Name muss exakt übereinstimmen `1` – Tag-Name wird als Teilzeichenkette gesucht (`LIKE '%name%'`) Beispiel: `0`
`StrictANDCondition`	bit boolean	0	Obsolet, wird nicht verwendet. Beispiel: `0`
`RowCount`	int	1000	Maximale Anzahl gelieferter Aufträge. NULL wird als 1000 behandelt. Beispiel: `500`
`DateFrom`	datetime dateTime	NULL	Beginn des Auftragsdatumsbereichs (inklusiv). NULL bedeutet 6 Monate vor jetzt. Beispiel: `2024-01-01T00:00:00`
`DateTo`	datetime dateTime	NULL	Ende des Auftragsdatumsbereichs (exklusiv). NULL bedeutet jetzt. Beispiel: `2024-07-01T00:00:00`

Antwort

Result-Set 1 · Wenn mindestens ein Filtereintrag die Prüfung nicht besteht oder das XML nicht lesbar ist; es folgt keine Auftragsliste

Prüfliste aller aufgelösten Filtereinträge. Bei einem Parse-Fehler wird eine einzelne Zeile mit NULL-Werten und Fehlermeldung geliefert.

Spalte	Typ	Beschreibung
`Operation` Kann leer sein	varchar(3) string	Filteroperation: `AND`, `OR` oder `NOT`
`XMLTagId` Kann leer sein	nvarchar(1024) string	TagId wie im XML angegeben
`XMLTagName` Kann leer sein	nvarchar(1024) string	TagName wie im XML angegeben (getrimmt)
`TagId` Kann leer sein	int	Id des aufgelösten Tags, NULL wenn nicht gefunden
`TagName` Kann leer sein	varchar(50) string	Name des aufgelösten Tags
`Status`	varchar(10) string	`OK` oder `ERROR`
`StatusMessage`	varchar(100) string	Treffer- oder Fehlerbeschreibung, z. B. `Complete match on TagId`, `Complete match on TagName`, `Partial match on TagName` oder eine Fehlermeldung

Result-Set 2 · Bei erfolgreicher Prüfung

Passende Aufträge, höchstens RowCount Zeilen, aufsteigend nach Auftragsschlüssel sortiert.

Spalte	Typ	Beschreibung
`OrderHeaderId`	int	Interner Auftragsschlüssel (`OrderHeaderKey`)
`OrderNr` Kann leer sein	string	Pixi-Auftragsnummer
`OrderNrExternal` Kann leer sein	string	Externe Auftragsnummer (z. B. aus dem Shop)

Beispielantwort

<SqlRowSet1>
  <row>
    <Operation>AND</Operation>
    <XMLTagId>12</XMLTagId>
    <TagId>12</TagId>
    <TagName>Priority</TagName>
    <Status>ERROR</Status>
    <StatusMessage>Tag used in another operation</StatusMessage>
  </row>
  <row>
    <Operation>NOT</Operation>
    <XMLTagName>Blocked</XMLTagName>
    <Status>ERROR</Status>
    <StatusMessage>TagId or TagName not found</StatusMessage>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
ERROR	TagId or TagName not found	Eine `TagId` oder ein `TagName` im Filter passt zu keinem Tag vom Typ 2. Tag-Id oder -Namen prüfen oder `PartialTagNameMatch` = 1 verwenden.
ERROR	Tag used in another operation	Derselbe Tag wird mehrfach aufgelöst, z. B. in zwei Operationen, per Id und per Name oder durch überlappende Teiltreffer. Jeden Tag nur einmal referenzieren.
ERROR	Unexpected error occured while parsing the @TagFilter parameter	`TagFilter` ist kein gültiges XML oder ein `TagId`-Wert ist nicht in eine Zahl umwandelbar. Wohlgeformtes XML mit numerischen Tag-Ids senden.

Beispiele

POST https://apigateway.descartes.com/tms/pixi/
Content-Type: text/xml; charset=utf-8
Authorization: Basic BASE64(USERNAME:PASSWORD)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiOrderGetByTags>
      <TagFilter><![CDATA[<TagFilter><AND><TagId>12</TagId><TagName>Express</TagName></AND><OR><TagId>15</TagId><TagName>Marketplace</TagName></OR><NOT><TagId>7</TagId><TagName>Blocked</TagName></NOT></TagFilter>]]></TagFilter>
      <!-- <PartialTagNameMatch>0</PartialTagNameMatch> -->
      <!-- <StrictANDCondition>0</StrictANDCondition> -->
      <!-- <RowCount>500</RowCount> -->
      <!-- <DateFrom>2024-01-01T00:00:00</DateFrom> -->
      <!-- <DateTo>2024-07-01T00:00:00</DateTo> -->
    </ns1:pixiOrderGetByTags>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

curl -X POST 'https://apigateway.descartes.com/tms/pixi/' \
  --user 'USERNAME:PASSWORD' \
  --header 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @- <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiOrderGetByTags>
      <TagFilter><![CDATA[<TagFilter><AND><TagId>12</TagId><TagName>Express</TagName></AND><OR><TagId>15</TagId><TagName>Marketplace</TagName></OR><NOT><TagId>7</TagId><TagName>Blocked</TagName></NOT></TagFilter>]]></TagFilter>
      <!-- <PartialTagNameMatch>0</PartialTagNameMatch> -->
      <!-- <StrictANDCondition>0</StrictANDCondition> -->
      <!-- <RowCount>500</RowCount> -->
      <!-- <DateFrom>2024-01-01T00:00:00</DateFrom> -->
      <!-- <DateTo>2024-07-01T00:00:00</DateTo> -->
    </ns1:pixiOrderGetByTags>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

<?php

$soapClient = new SoapClient(null, [
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
    'location' => 'https://apigateway.descartes.com/tms/pixi/',
    'uri' => 'https://apigateway.descartes.com/tms/pixi/',
]);

$arguments = [
    'TagFilter' => '<TagFilter><AND><TagId>12</TagId><TagName>Express</TagName></AND><OR><TagId>15</TagId><TagName>Marketplace</TagName></OR><NOT><TagId>7</TagId><TagName>Blocked</TagName></NOT></TagFilter>',
    // 'PartialTagNameMatch' => '0',
    // 'StrictANDCondition' => '0',
    // 'RowCount' => '500',
    // 'DateFrom' => '2024-01-01T00:00:00',
    // 'DateTo' => '2024-07-01T00:00:00',
];

$soapArguments = [];
foreach ($arguments as $name => $value) {
    $soapArguments[] = new SoapVar($value, XSD_STRING, '', '', $name);
}

$response = $soapClient->__soapCall('pixiOrderGetByTags', $soapArguments);

Verwendete Tabellen

Tag · Lesen TagMatch · Lesen OrderHeader · Lesen

SQL-Objekt:: dbo.pipiOrderGetByTags