Commerce-REST-API-Referenz (private Vorschau)

Notiz

Web IQ Commerce steht in der privaten Vorschau für eine ausgewählte Gruppe von Azure Kunden zur Verfügung. Während der privaten Vorschau wird die Nutzung bei 7,00 $ pro 1.000 API-Aufrufen in Rechnung gestellt. Die API-Oberfläche und der Vertrag können sich ändern.

Berechtigte Kunden können die Commerce-APIs im Playground im Web IQ Developer Portal ausprobieren. Wenn Sie den Playground noch nicht verwendet haben, beginnen Sie mit der Schnellstartanleitung.

Wir erweitern den Zugriff während der privaten Vorschau. Der Zugriff ist nicht garantiert. Wenn Sie Zugriff anfordern oder Fragen stellen möchten, öffnen Sie eine Web IQ-Supportanfrage, wählen Sie Authentifizierung und Zugriff als Problemtyp und API-Schlüsselsetup als Untertyp aus, wählen Sie "Supportanfrage erstellen" aus, und schließen Sie Ihre AppID (kopieren Sie sie aus der Profilverwaltung im Web IQ Developer Portal) ein oder, wenn Sie noch keinen haben, Ihren Firmennamen und den Namen Ihrer Web IQ-Ressource.

Die Web IQ Commerce APIs sind Commerce Search, Angebote und Produktdetails. Die Commerce Search gibt bewertete Produkte und Verkäuferangebote für eine Produktabfrage zurück. Verwenden Sie die verfügbaren Produkt-, SKU- und Angebots-IDs mit Angeboten. Produktdetails akzeptieren Produkt- und SKU-IDs.

Alle drei Endpunkte akzeptieren POST Anforderungen mit einem JSON-Textkörper. Authentifizieren mit einem API-Schlüssel, der für Commerce im x-apikey Header aktiviert ist, oder mit einem Microsoft Entra ID Zugriffstoken im Authorization Header. Anweisungen zum Einrichten finden Sie unter "Authentifizierung ".

Beispiele verwenden fiktive Contoso-Produkte, Verkäufer, Bezeichner, URLs und Preise. Ersetzen Sie Beispiel-IDs durch Werte aus Ihrer E-Commerce-Suchantwort, wenn Sie Nachverfolgungsanforderungen durchführen.

Anfrage-Header

Header Typ Description
x-apikey oder Autorisierung string Ihr API-Schlüssel oder Entra ID Zugriffstoken für die Authentifizierung.
Inhaltstyp string MIME-Typ des Anforderungstexts. Verwenden Sie application/json.

Unterstützte Märkte

Während der privaten Vorschau unterstützen die Commerce-APIs diese Kombinationen und languageregion. Andere Kombinationen werden nicht unterstützt.

Markt language region
Englisch (USA) en US
Spanisch (USA) es US
Englisch (Kanada) en CA
Französisch (Kanada) fr CA
Walisisch (Großbritannien) en GB
Deutsch (Deutschland) de DE
Französisch (Frankreich) fr FR
Englisch (Australien) en AU
Japanisch (Japan) ja JP

Verwenden Sie für jedes angebot, das Sie präsentieren, genau clickUrl wie in dieser Antwort zurückgegeben, für jeden Link oder jede Navigation zum Angebot, ob von einem Benutzer oder von einem Agenten, der für den Benutzer tätig ist. clickUrl Standardmäßig handelt es sich um eine Microsoft gehostete Umleitung; Microsoft können auch eine direkte Händler-URL zurückgeben. Verwenden Sie displayUrl nur, um den Händler oder Verkäufer in Ihrer Anzeige oder als Modellkontext zu identifizieren, niemals als Link oder Navigationsziel. Wenn ein Angebot nicht nutzbar clickUrlist, stellen Sie das Angebot nicht vor.

Als undurchsichtig behandeln clickUrl . Der Attributionsparameter ist erforderlich und kann sich innerhalb der Umleitung befinden, sodass er möglicherweise nicht sichtbar ist. Entfernen, neu schreiben, abschneiden, decodieren oder ersetzen Sie den clickUrl oder dessen Attributionsparameter, und umgehen Sie die Umleitungen nicht, oder fügen Sie einen Parameter selbst hinzu. Sie können einen clickUrl Umleitungslink nur in Ihrem eigenen Tracking- oder Umleitungslink umschließen, wenn er das Original clickUrl durch unverändert übergibt. Verwenden Sie keine Wiederverwendung für clickUrl eine andere Antwort, Abfrage, Einen Benutzer oder einen anderen Zweck, einschließlich über einen Cache. Die eigene Freigabe oder Weiterleitung eines Endbenutzers wird nicht wiederverwendet.

Erstellen Sie jeden Link im Anwendungscode aus der clickUrl Antwort, anstatt ein Modell zu reproduzieren. Die geltenden Bedingungen finden Sie unter Anlage B der Web IQ Nutzungsbedingungen.

Endpunkt:POST https://api.microsoft.ai/v3/search/commerce/products

Gibt bewertete Produkte und Verkäuferangebote für eine Produktabfrage zurück. Verwenden Sie die verfügbaren Produkt-, SKU- und Angebots-IDs mit Angeboten. Produktdetails akzeptieren Produkt- und SKU-IDs.

Beispielanforderung für die Commerce-Suche

curl -X POST "https://api.microsoft.ai/v3/search/commerce/products" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "Contoso wireless headphones",
    "maxResults": 1,
    "language": "en",
    "region": "US",
    "location": "lat:37.7749;long:-122.4194"
  }'

Parameter für die Commerce-Suche

Parameter Required Typ Vorgabe Description
query Yes string - Produktsuchabfrage, die nicht leer ist. Die maximale Länge beträgt 1.000 Zeichen.
maxResults No integer 10 Maximale Anzahl der zurückzugebenden Produkte von 1 bis 50.
language No string en Iso 639-1 Ergebnissprache mit zwei Buchstaben. Siehe unterstützte Märkte.
region No string US Code für Land oder Region mit zwei Buchstaben. Siehe unterstützte Märkte.
location No string - Speicherort im lat:<latitude>;long:<longitude> Format, z. B lat:37.7749;long:-122.4194. . Breitengrad muss von -90 bis 90 und Längengrad von -180 bis 180 sein.

Antwort auf die Commerce-Suche

Gibt eine CommerceResponse mit bewerteten Produkten und ihren Angeboten zurück. Wenn keine Produkte übereinstimmen, befindet 200 OK sich die Antwort mit einem leeren products Array.

Beispielantwort 200 OK (Auszug):

{
  "products": [
    {
      "offers": [
        {
          "id": "100000000001",
          "name": "Contoso Wireless Headphones",
          "seller": {
            "name": "Contoso Electronics",
            "logoUrl": "https://contoso.example/logo.png"
          },
          "price": { "listPrice": 10000, "offeredPrice": 9000, "currency": "USD" }
        }
      ],
      "id": "PG_00000000000000000000000000000001",
      "skuId": "00000000000000000000000000000001"
    }
  ],
  "traceId": "<trace-id>"
}

Commerce Search-Fehler

Ein fehlender, leerer oder überlanger queryWert, ein außerhalb des Bereichs maxResults, ein language oder region nicht zwei Zeichen oder eine ungültige location Rückgabe 400 (HandlerInvalidInput). Dienstfehler werden zurückgegeben 500 (InternalServerError). Informationen zu Authentifizierungs-, Autorisierungs-, Format- und Kontingentfehlern finden Sie unter "Fehler".

Grenzwerte für die Commerce-Suche

  • query: 1 bis 1.000 Zeichen und nicht nur Leerzeichen.
  • maxResults: 1 bis 50, Standard 10. Die Anzahl der zurückgegebenen Produkte hängt von den verfügbaren Übereinstimmungen ab. Es gibt keine Paginierung und keinen Parameter für die Anzahl der Angebote pro Produkt.
  • language und region: zweistellige Codes. location Koordinaten müssen sich innerhalb der Bereiche in der Parametertabelle befinden.
  • Die Ratenlimits und das tägliche Kontingent Ihres App-Profils (AppID) gelten ebenfalls.

Offers

Endpunkt:POST https://api.microsoft.ai/v3/fetch/commerce/products/offers

Gibt berechtigte Verkäuferangebote für ein Produkt, eine SKU oder ein repräsentatives Angebot aus der Commerce Search zurück. Es gibt Verkäuferangebote zurück, kein Feedback auf Produktebene oder Preisverlauf.

Beispielanforderung für Angebote

curl -X POST "https://api.microsoft.ai/v3/fetch/commerce/products/offers" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "productId": "PG_00000000000000000000000000000001",
    "skuId": "00000000000000000000000000000001",
    "offerId": "100000000001",
    "language": "en",
    "region": "US"
  }'

Angebotsparameter

Senden Sie alle verfügbaren Produkte, SKU und Angebotskennungen für das ausgewählte Produkt aus der Antwort "Commerce Search". Wenn nur ein Bezeichner zurückgegeben wird, senden Sie diesen Bezeichner. Mindestens ein Bezeichner, der nicht leer ist, ist erforderlich; eine Anforderung ohne eine Rückgabe 400 (HandlerInvalidInput).

Parameter Required Typ Vorgabe Description
productId Bedingung string - Produkt id , das von der Commerce-Suche zurückgegeben wird. Maximal 1.000 Zeichen.
skuId Bedingung string - Produkt skuId , das von der Commerce-Suche zurückgegeben wird. Maximal 1.000 Zeichen.
offerId Bedingung string - Repräsentatives Angebot id , das von der Commerce Search zurückgegeben wird. Maximal 1.000 Zeichen.
language No string en Iso 639-1 Ergebnissprache mit zwei Buchstaben. Siehe unterstützte Märkte.
region No string US Code für Land oder Region mit zwei Buchstaben. Siehe unterstützte Märkte.
location No string - Speicherort im lat:<latitude>;long:<longitude> Format. Breitengrad muss von -90 bis 90 und Längengrad von -180 bis 180 sein.

Antwort auf Angebote

CommerceOffersResponse

Feld Typ Description
offers Array von CommerceOffer Primäre oder repräsentative Angebote zuerst, gefolgt von zusätzlichen Angeboten.
traceId string Anforderungsablaufverfolgungs-ID für Debugging und Korrelation.

Informationen zu den Angebotsfeldern finden Sie unter CommerceOffer, CommerceOfferImage, CommerceInstallmentInfo und Unterstützende Objekte. Unbekannte Bezeichner werden mit einem leeren offers Array zurückgegeben200 OK.

Beispielantwort 200 OK (Auszug):

{
  "offers": [
    {
      "id": "100000000001",
      "name": "Contoso Wireless Headphones",
      "seller": {
        "name": "Contoso Electronics",
        "logoUrl": "https://contoso.example/logo.png"
      },
      "price": { "listPrice": 10000, "offeredPrice": 9000, "currency": "USD" }
    }
  ],
  "traceId": "<trace-id>"
}

Bietet Fehler

Ein fehlender oder leerer Bezeichner, ein Bezeichner mit mehr als 1.000 Zeichen, ein language oder nicht zwei Zeichen oder eine ungültige location400 Rückgabe (HandlerInvalidInputregion). Unbekannte Bezeichner werden mit einem leeren offers Array zurückgegeben200 OK. Dienstfehler werden zurückgegeben 500 (InternalServerError). Siehe Fehler.

Grenzwerte für Angebote

  • Ein Produkt, eine SKU oder ein repräsentatives Angebot pro Anfrage; Batch-Nachschlagevorgänge werden nicht unterstützt. Jeder Bezeichner ist auf 1.000 Zeichen beschränkt.
  • Es gibt keinen maxResultsParameter für Offset oder Cursor. Die Anzahl der Angebote hängt von der Verfügbarkeit ab.
  • language und region: zweistellige Codes. location Koordinaten müssen sich innerhalb der Bereiche in der Parametertabelle befinden.
  • Die Ratenlimits und das tägliche Kontingent Ihres App-Profils (AppID) gelten ebenfalls.

Produktdetails

Endpunkt:POST https://api.microsoft.ai/v3/fetch/commerce/products/details

Gibt den Produkttitel (name), die Beschreibung und die aggregierte Bewertung für eine Produkt-ID, eine SKU-ID oder beides aus der Commerce-Suche zurück. Die Beschreibung ist bei Verfügbarkeit enthalten.

Beispielanforderung für Produktdetails

curl -X POST "https://api.microsoft.ai/v3/fetch/commerce/products/details" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "productId": "PG_00000000000000000000000000000002",
    "skuId": "00000000000000000000000000000002",
    "language": "en",
    "region": "US"
  }'

Parameter für Produktdetails

Mindestens eine productId oder skuId die nicht leer ist, ist erforderlich, und Sie können beides senden. offerId ist keine Alternative: Eine Anforderung mit nur einer Angebots-ID schlägt die Validierung fehl.

Parameter Required Typ Vorgabe Description
productId Bedingung string - Produkt id aus der Commerce-Suche. Erforderlich, wenn keine skuId gesendet wird. Maximal 1.000 Zeichen.
skuId Bedingung string - SKU-ID aus der Commerce-Suche. Erforderlich, wenn keine productId gesendet wird. Maximal 1.000 Zeichen.
language No string en Code mit zwei Buchstaben. Wenn sie nicht angegeben oder nullverwendet wird, wird der Standardwert verwendet. Siehe unterstützte Märkte.
region No string US Code für den Zwei-Buchstaben-Regionscode für die Produktsuche. Wenn sie nicht angegeben oder nullverwendet wird, wird der Standardwert verwendet. Siehe unterstützte Märkte.

Antwort auf Produktdetails

CommerceProductDetailsResponse

Feld Typ Description
products Array von CommerceProductDetails Null oder ein übereinstimmende Produkt. Batch-Nachschlagevorgänge werden nicht unterstützt.
traceId string Anforderungsablaufverfolgungs-ID.

CommerceProductDetails

Feld Typ Description
id string Produkt-ID über Varianten hinweg, übereinstimmende Commerce-Suche.
name string Produkttitel, sofern verfügbar.
description string Produktbeschreibung, sofern verfügbar.
rating CommerceRating Die Durchschnittliche Bewertungs- und Bewertungsanzahl des Produkts auf einer Skala von 1 bis 5.

CommerceRating

Das rating Objekt wird weggelassen, wenn keine Bewertung verfügbar ist.

Feld Typ Description
value Zahl Die Durchschnittliche Produktbewertung wird auf zwei Dezimalstellen gerundet.
scaleMin Zahl Ende der Bewertungsskala (1).
scaleMax Zahl Oberer Rand der Bewertungsskala (5).
count integer Anzahl der Bewertungen für das Produkt. Es wird eine Anzahl von Null zurückgegeben als 0.

Unbekannte Produkte werden mit einem leeren products Array zurückgegeben200 OK.

Beispielantwort 200 OK :

{
  "products": [
    {
      "id": "PG_00000000000000000000000000000002",
      "name": "Contoso Wireless Earbuds",
      "description": "Illustrative wireless in-ear headphones",
      "rating": { "value": 4.2, "scaleMin": 1, "scaleMax": 5, "count": 42 }
    }
  ],
  "traceId": "<trace-id>"
}

Fehler bei Produktdetails

Ein fehlender oder leerer Produkt- oder SKU-Bezeichner, ein Bezeichner mit mehr als 1.000 Zeichen oder ein language oder region nicht zwei Zeichen gibt 400 zurück (HandlerInvalidInput). Dienstfehler werden zurückgegeben 500 (InternalServerError). Siehe Fehler.

Grenzwerte für Produktdetails

  • Mindestens ein Produkt- oder SKU-Bezeichner, jeweils bis zu 1.000 Zeichen. Batch-Nachschlagevorgänge und -nachschlagevorgänge nach Angebots-ID werden nur nicht unterstützt.
  • language und region: zweistellige Codes.
  • Die Ratenlimits und das tägliche Kontingent Ihres App-Profils (AppID) gelten ebenfalls.

Antwortobjekte

Diese Objekte werden von Commerce Search and Offers zurückgegeben.

CommerceResponse

Feld Typ Description
products Array von CommerceProduct Produkte in Rangreihenfolge.
traceId string Anforderungsablaufverfolgungs-ID für Debugging und Korrelation.

CommerceProduct

Feld Typ Description
id string Produktbezeichner über Varianten hinweg.
skuId string SKU-Id des Katalogs.
offers Array von CommerceOffer Primäre Verkäuferangebote.

CommerceOffer

Feld Typ Description
id string Angebots-ID.
name string Verkäufertitel.
description string Verkäuferbeschreibung.
specifications Array von CommerceSpecification Spezifikationen und ausgewählte Attribute auf Angebotsebene. Duplikate und Quellreihenfolge bleiben erhalten. Siehe Unterstützende Objekte.
seller CommerceSeller Händlerdetails. Siehe Unterstützende Objekte.
price CommerceOfferPrice Angebotspreis in ISO 4217-Nebeneinheiten. offeredPrice fällt zurück auf listPrice den Fall, wenn kein Rabattpreis vorhanden ist. Siehe Unterstützende Objekte.
displayUrl string Händler- oder Verkäufer-URL, nur für Anzeige- oder Modellkontext. Verwenden Sie sie nicht als Link- oder Navigationsziel.
clickUrl string Ziel für jeden Link oder jede Navigation zum Angebot. Verwenden Sie sie genau wie zurückgegeben. Siehe Angebotslinks und Attribution.
images Array von CommerceOfferImage Bieten Sie Bilder an.
installmentInfo CommerceInstallmentInfo Zahlungsdetails für Die Installation.
shippingInfo string Versandinformationen als lesbarer Text.
condition string Vom Verkäufer bereitgestellte Bedingung des angebotenen Artikels.

CommerceOfferImage

Feld Typ Description
url string Bild-URL.

CommerceInstallmentInfo

Feld Typ Description
description string Beschreibung des Installationsplans als lesbarer Text.
downPayment CommercePrice Der betrag ist im Voraus erforderlich. Siehe Unterstützende Objekte.
monthlyPayment CommercePrice Monatliche Ratenzahlung. Siehe Unterstützende Objekte.
months integer Anzahl von Monaten.

Unterstützen von Objekten

Die Preise sind ganze Zahlen in ISO 4217 Nebeneinheiten der Währung. Beispiel: 10000 Mit currencyUSD 100,00 $

Object Feld Typ Description
CommerceOfferPrice listPrice integer Originalpreis in ISO 4217-Nebeneinheiten.
CommerceOfferPrice offeredPrice integer Aktueller Preis in ISO 4217-Nebeneinheiten. Fällt zurück, listPrice wenn kein Rabattpreis verfügbar ist.
CommerceOfferPrice currency string ISO 4217-Währungscode.
CommercePrice amount integer Zahlungsbetrag in ISO 4217-Nebeneinheiten.
CommercePrice currency string ISO 4217-Währungscode.
CommerceSeller name string Anzeigename des Händlers.
CommerceSeller logoUrl string Händlerlogo-URL.
CommerceSpecification name string Angebotsattributename.
CommerceSpecification values Array von Strings Attributanzeigewerte, Beibehalten von Duplikaten und Quellreihenfolge.

Fehler

Diese Fehler gelten für alle drei Endpunkte. Das Überprüfungs- und Leerergebnisverhalten jedes Endpunkts wird in einem eigenen Abschnitt beschrieben.

HTTP-Status Fehlercode Bedeutung und Handlung
400 RequestInvalidFormat, HandlerInvalidInput Falsch formatierter JSON-Code oder Anforderungsparameter, die fehlen oder ungültig sind. Korrigieren Sie die Anforderung mithilfe der Parametertabelle und -grenzwerte des Endpunkts.
401 Authentifizierungsfehler, z AuthNoToken . B. oder AuthInvalidApiKey Anmeldeinformationen fehlen, ungültig oder abgelaufen. Authentifizieren Sie sich erneut mit gültigen Anmeldeinformationen.
403 AuthUnauthorizedService Der Aufrufer ist nicht berechtigt, auf die angeforderte Ressource zuzugreifen. Wenn Ihr App-Profil nicht für Commerce aktiviert ist, fordern Sie den Zugriff an, wie oben auf dieser Seite beschrieben.
405 MethodNotAllowed Verwenden Sie POST, nicht GET.
415 RequestUnsupportedMediaType Senden content-type: application/json.
429 AuthUserThrottled, AuthUserDailyUsageExceeded Der Satzgrenzwert oder das tägliche Kontingent Ihres App-Profils (AppID) wurde überschritten. Warten Sie, bis die Zeit eingedauert retryAfter ist, bevor Sie den Vorgang wiederholen.
500 InternalServerError Der Dienst konnte die Anfrage nicht erfüllen. Wiederholen Sie den Vorgang nach der angegebenen Verzögerung, und schließen Sie den Zeitpunkt ein, wenn Sie sich an den traceId Support wenden.

Fehlerantwort

Fehler verwenden die Freigegebene Fehlerantwortstruktur.

Feld Typ Description
errorCode string Maschinenlesbarer Fehlercode.
errorCategory string UserError oder SystemError.
userMessage string Lesbare Erklärung des Fehlers.
technicalDetails string Optionale Diagnosedetails.
retryAfter string Optionale Wiederholungsverzögerung in Sekunden, gefolgt von einem s Suffix (z. B "60s". ).
requestId string Optionaler Anforderungsbezeichner.
traceId string Optionaler verteilter Ablaufverfolgungsbezeichner zur Unterstützung.

Fehlerbeispiel

Eine Commerce Search-Anforderung ohne query:

curl -X POST "https://api.microsoft.ai/v3/search/commerce/products" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{}'

400 Bad Request Antwort:

{
  "errorCode": "HandlerInvalidInput",
  "errorCategory": "UserError",
  "userMessage": "Invalid input provided. Please check your request parameters.",
  "technicalDetails": "query is required",
  "traceId": "<trace-id>"
}

Ratenbegrenzungen

Alle drei Endpunkte verwenden die Ratenlimits und das tägliche Kontingent Ihrer Web IQ AppID (standardmäßig 15 Abfragen pro Sekunde), die für die anderen Web IQ-APIs freigegeben sind, die appID-Aufrufe. Eine 429 Antwort enthält die Wiederholungsverzögerung in retryAfter. Tägliche Kontingente werden um 00:00 UTC zurückgesetzt. Anleitungen zur Wiederholung finden Sie unter "Fehlerbehandlung".