Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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 |
Anbieten von Links und Zuschreibung
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.
Commerce-Suche
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, Standard10. 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. -
languageundregion: zweistellige Codes.locationKoordinaten 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. -
languageundregion: zweistellige Codes.locationKoordinaten 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.
-
languageundregion: 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".