Items Schreiben

pixiSetItemTags

Gleicht die Tags mit Präfix der im XML übergebenen Artikel ab: legt fehlende Tags an, ergänzt neue Zuordnungen und entfernt nicht mehr aufgeführte Zuordnungen mit Präfix.

Setzt die Tags eines oder mehrerer Artikel aus dem XML-Dokument in TagsXML. Der Aufruf arbeitet als Ersetzen je Artikel für alle Tags, deren Name mit TagPrefix beginnt.

Ablauf:

Jedes Element /ItemTags/Item/TagList/Tag ergibt eine Zeile. Der Tag-Name wird als TagPrefix + Name gebildet (ein leerer Name ergibt keinen Namen). Leere Werte für ItemNrInt, EANUPC sowie ItemKey = 0 gelten als nicht angegeben.
Der Artikel wird in drei Durchläufen gegen Items aufgelöst: zuerst über ItemKey, dann über ItemNrInt, dann über EANUPC. Ein späterer Treffer überschreibt einen früheren; zeigen mehrere Kennungen auf unterschiedliche Artikel, gewinnt der EAN-Treffer. Zeilen, deren Artikel nicht gefunden wird, werden ohne Meldung verworfen.
Noch nicht vorhandene Tags (Typ 1, kein System-Tag) werden über den Namen in Tag angelegt. Kommt derselbe Name mit unterschiedlichen Beschreibungen vor, wird die alphabetisch größte Beschreibung verwendet; eine fehlende Beschreibung wird als Leerstring gespeichert. Beschreibungen bestehender Tags werden nicht geändert.
Für jeden im XML enthaltenen Artikel werden alle bestehenden Zuordnungen in TagMatch zu Tags vom Typ 1, deren Name TagPrefix% entspricht und die für diesen Artikel nicht aufgeführt sind, gelöscht. Tags ohne Präfix bleiben unverändert. Ein Artikel, der nur mit leerem Tag-Namen übergeben wird, verliert dadurch alle Tags mit Präfix.
Aufgeführte, noch nicht vorhandene Zuordnungen werden in TagMatch eingefügt.

Das Ergebnis listet die neu eingefügten Zuordnungen mit Action = ADDED. Artikel, die mit leerem Tag-Namen übergeben wurden, erscheinen zusätzlich einmal mit Action = DELETED und leerem TagKey/TagName. Die einzelnen entfernten Zuordnungen werden nicht zurückgegeben.

Hinweise

Keine explizite Transaktion: Anlage von Tags, Löschungen und Einfügungen sind getrennte Anweisungen; ein Fehler dazwischen kann einen Teilzustand hinterlassen.
Lesezugriffe auf Items und Tag erfolgen mit NOLOCK.
TagPrefix wird in einem LIKE-Muster verwendet; % oder _ im Präfix wirken als Platzhalter und können die Menge der zu entfernenden Tags erweitern. Ein leeres Präfix macht alle Tags vom Typ 1 der übergebenen Artikel zu Löschkandidaten. Ein Präfix NULL ergibt keine Tag-Namen, sodass weder hinzugefügt noch entfernt wird.
Das XML-Element Name wird als varchar(50), Description als varchar(500), EANUPC als varchar(13) gelesen; längere Werte werden abgeschnitten. Ob Präfix + Name in Tag.Name passt, hängt von der nicht sichtbaren Tabellendefinition ab.
Das Dokument-Handle aus sp_xml_preparedocument wird nie mit sp_xml_removedocument freigegeben; es bleibt bis zum Ende der Verbindung belegt.
Es werden keine Fehlerzeilen geliefert; unbekannte Artikel werden stillschweigend ignoriert.

Parameter

Parameter Typ Standardwert Beschreibung

Parameter	Typ	Standardwert	Beschreibung
`TagsXML`	varchar(max) xml	NULL	XML-Dokument mit den Artikeln und ihrer Tag-Liste. Jedes `Item` identifiziert den Artikel über `ItemKey`, `ItemNrInt` und/oder `EANUPC` und enthält eine `TagList` mit `Tag`-Elementen (`Name`, `Description`). Ein leerer `Name` bewirkt, dass alle Tags mit Präfix des Artikels entfernt werden. Beispiel: `<ItemTags> <Item> <ItemKey>1234</ItemKey> <ItemNrInt>A-1000</ItemNrInt> <EANUPC>4012345678901</EANUPC> <TagList> <Tag> <Name>Sale</Name> <Description>Summer sale 2024</Description> </Tag> <Tag> <Name>New</Name> <Description/> </Tag> </TagList> </Item> </ItemTags>`
`TagPrefix`	varchar(20) string	API	Präfix, das jedem Tag-Namen aus dem XML vorangestellt wird. Nur Zuordnungen zu Tags, deren Name mit diesem Präfix beginnt, werden abgeglichen (entfernt, wenn nicht aufgeführt). Das Leerzeichen am Ende des Standardwerts beachten. Beispiel: `API`

TagsXML

varchar(max)
xml

NULL

XML-Dokument mit den Artikeln und ihrer Tag-Liste. Jedes Item identifiziert den Artikel über ItemKey, ItemNrInt und/oder EANUPC und enthält eine TagList mit Tag-Elementen (Name, Description). Ein leerer Name bewirkt, dass alle Tags mit Präfix des Artikels entfernt werden.

Beispiel:

<ItemTags>
  <Item>
    <ItemKey>1234</ItemKey>
    <ItemNrInt>A-1000</ItemNrInt>
    <EANUPC>4012345678901</EANUPC>
    <TagList>
      <Tag>
        <Name>Sale</Name>
        <Description>Summer sale 2024</Description>
      </Tag>
      <Tag>
        <Name>New</Name>
        <Description/>
      </Tag>
    </TagList>
  </Item>
</ItemTags>

TagPrefix

varchar(20)
string

API

Präfix, das jedem Tag-Namen aus dem XML vorangestellt wird. Nur Zuordnungen zu Tags, deren Name mit diesem Präfix beginnt, werden abgeglichen (entfernt, wenn nicht aufgeführt). Das Leerzeichen am Ende des Standardwerts beachten.

Beispiel: API

Antwort

Result-Set 1 · Immer (ggf. leer)

Neu hinzugefügte Tag-Zuordnungen (ADDED) sowie für Artikel, die mit leerem Tag-Namen übergeben wurden, eine Markierungszeile (DELETED). Doppelte Zeilen werden durch UNION entfernt.

Spalte	Typ	Beschreibung
`TagKey` Kann leer sein	int	ID des Tags (`Tag.Id`); leer bei `DELETED`-Zeilen.
`TagName` Kann leer sein	string	Vollständiger Tag-Name inklusive Präfix; leer bei `DELETED`-Zeilen.
`ItemKey`	int	Schlüssel des aufgelösten Artikels.
`Action`	varchar(7) string	`ADDED` für eine neu eingefügte Zuordnung, `DELETED` für einen Artikel, dessen Tags mit Präfix über einen leeren Tag-Namen entfernt wurden.

Beispielantwort

<SqlRowSet1>
  <row>
    <TagKey>17</TagKey>
    <TagName>API Sale</TagName>
    <ItemKey>1234</ItemKey>
    <Action>ADDED</Action>
  </row>
  <row>
    <TagKey>18</TagKey>
    <TagName>API New</TagName>
    <ItemKey>1234</ItemKey>
    <Action>ADDED</Action>
  </row>
</SqlRowSet1>

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:pixiSetItemTags>
      <!-- <TagsXML><![CDATA[<ItemTags><Item><ItemKey>1234</ItemKey><ItemNrInt>A-1000</ItemNrInt><EANUPC>4012345678901</EANUPC><TagList><Tag><Name>Sale</Name><Description>Summer sale 2024</Description></Tag><Tag><Name>New</Name><Description></Description></Tag></TagList></Item></ItemTags>]]></TagsXML> -->
      <!-- <TagPrefix>API</TagPrefix> -->
    </ns1:pixiSetItemTags>
  </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:pixiSetItemTags>
      <!-- <TagsXML><![CDATA[<ItemTags><Item><ItemKey>1234</ItemKey><ItemNrInt>A-1000</ItemNrInt><EANUPC>4012345678901</EANUPC><TagList><Tag><Name>Sale</Name><Description>Summer sale 2024</Description></Tag><Tag><Name>New</Name><Description></Description></Tag></TagList></Item></ItemTags>]]></TagsXML> -->
      <!-- <TagPrefix>API</TagPrefix> -->
    </ns1:pixiSetItemTags>
  </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 = [
    // 'TagsXML' => '<ItemTags><Item><ItemKey>1234</ItemKey><ItemNrInt>A-1000</ItemNrInt><EANUPC>4012345678901</EANUPC><TagList><Tag><Name>Sale</Name><Description>Summer sale 2024</Description></Tag><Tag><Name>New</Name><Description></Description></Tag></TagList></Item></ItemTags>',
    // 'TagPrefix' => 'API',
];

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

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

Verwendete Tabellen

Items · Lesen Tag · Schreiben TagMatch · Schreiben

SQL-Objekt:: dbo.pipiSetItemTags