Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
Note
Web IQ Commerce özel önizleme aşamasındadır ve tam belge erişimine sahip AppID'lere dahildir. Arama, Teklifler ve Ürün Ayrıntıları için erişim ayrı olarak etkinleştirilir. Özel önizleme sırasında kullanım, 1.000 API çağrısı başına 7,00 ABD doları olarak faturalandırılır. API yüzeyi ve sözleşmesi değişebilir.
Uygun müşteriler, Web IQ Geliştirici Portalı'ndaki Playground'da Ticaret API'lerini deneyebilir. Daha önce Playground'ı kullanmadıysanız Hızlı Başlangıç ile başlayın.
AppID'nizde Ticaret API'leri yoksa veya sorularınız varsa bir Web IQ Destek isteği açın, sorun türü olarak Kimlik Doğrulaması ve Erişim'i seçin ve alt tür olarak API Anahtarı Kurulumu'na tıklayın, Destek isteği oluştur'u seçin ve AppID'nizi ekleyin (Web IQ Geliştirici Portalı'nda Profil Yönetimi'nden kopyalayın) veya henüz yoksa, şirketinizin adı ve Web IQ kaynağınızın adı.
Web IQ Ticaret API'leri Ticaret Arama, Teklifler ve Ürün Ayrıntıları'dır. Commerce Search, bir ürün sorgusu için dereceli ürünleri ve satıcı tekliflerini döndürür. Teklifler ile kullanılabilir ürün, SKU ve teklif tanımlayıcılarını kullanın. Ürün Ayrıntıları ürün ve SKU tanımlayıcılarını kabul eder.
Üç uç nokta da JSON gövdesine sahip istekleri kabul POST eder. Üst bilgide Commerce için etkinleştirilmiş bir API anahtarıyla veya üst bilgide x-apikey Microsoft Entra ID erişim belirteci ile kimlik doğrulaması yapınAuthorization. Kurulum yönergeleri için bkz. Kimlik doğrulaması .
Örneklerde kurgusal Contoso ürünleri, satıcılar, tanımlayıcılar, URL'ler ve fiyatlar kullanılır. İzleme istekleri yaparken örnek tanımlayıcıları Commerce Search yanıtınızın değerleriyle değiştirin.
İstek başlıkları
| Başlık | Type | Description |
|---|---|---|
| x-apikey veya Yetkilendirme | string | Kimlik doğrulaması için API anahtarınız veya Entra ID erişim belirteciniz. |
| içerik türü | string | İstek gövdesinin MIME türü.
application/json adresini kullanın. |
Desteklenen pazarlar
Özel önizleme sırasında, Ticaret API'leri ve birleşimlerini languageregiondestekler. Diğer birleşimler desteklenmez.
| Pazar | language |
region |
|---|---|---|
| İngilizce (ABD) | en |
US |
| İspanyolca (ABD) | es |
US |
| İngilizce (Kanada) | en |
CA |
| Fransızca (Kanada) | fr |
CA |
| İngilizce (Birleşik Krallık) | en |
GB |
| Almanca (Almanya) | de |
DE |
| Fransızca (Fransa) | fr |
FR |
| İngilizce (Avustralya) | en |
AU |
| Japonca (Japonya) | ja |
JP |
Teklif bağlantıları ve ilişkilendirme
Sunduğunız her teklif için, bir kullanıcı veya kullanıcı için hareket eden bir aracı tarafından teklife yönelik her bağlantı veya gezinti için tam olarak bu yanıtta döndürülen şekilde kullanın clickUrl . Varsayılan olarak, clickUrl Microsoft barındırılan bir yeniden yönlendirmedir; Microsoft doğrudan satıcı URL'si de döndürebilir. Yalnızca ekranınızdaki satıcıyı veya satıcıyı tanımlamak veya model bağlamı olarak kullanın displayUrl ; hiçbir zaman bağlantı veya gezinti hedefi olarak kullanmayın. Bir teklifin kullanılabilir clickUrlbir teklifi yoksa teklifi sunmayın.
Opak gibi davran clickUrl . İlişkilendirme parametresi gereklidir ve yeniden yönlendirmenin içinde olabilir, bu nedenle görünür olmayabilir. veya ilişkilendirme parametresini ayırmayın, yeniden yazmayın, kesmeyin, kod çözmeyin veya değiştirmeyin clickUrl ve yönlendirmelerini atlamayın veya parametreyi kendiniz eklemeyin. Yalnızca özgün clickUrl bağlantıyı değiştirilmeden geçirirse, kendi izlemenize veya yeniden yönlendirme bağlantınıza sarmalayabilirsinizclickUrl. Önbellek aracılığıyla da dahil olmak üzere farklı bir yanıt, sorgu, kullanıcı veya amaç için yeniden kullanma clickUrl . Son kullanıcının kendi paylaşımı veya iletmesi yeniden kullanılmaz.
Uygulama kodundaki her bağlantıyı bir modelin clickUrl yeniden oluşturması yerine yanıttaki dosyasından oluşturun. Geçerli koşullar için bkz. Web IQ Kullanım Koşullarının B'sini Sergile.
Ticaret Arama
Uç nokta:POST https://api.microsoft.ai/v3/search/commerce/products
Bir ürün sorgusu için dereceli ürünleri ve satıcı tekliflerini döndürür. Teklifler ile kullanılabilir ürün, SKU ve teklif tanımlayıcılarını kullanın. Ürün Ayrıntıları ürün ve SKU tanımlayıcılarını kabul eder.
Ticaret Arama örnek isteği
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"
}'
Commerce Search parametreleri
| Parametre | Required | Type | Default | Description |
|---|---|---|---|---|
query |
Yes | string | - | Boş olmayan ürün arama sorgusu. Uzunluk üst sınırı 1.000 karakterdir. |
maxResults |
Hayır | integer | 10 |
Döndürülecek en fazla ürün sayısı 1 ila 50. |
language |
Hayır | string | en |
İki harfli ISO 639-1 sonuç dili. Bkz. Desteklenen pazarlar. |
region |
Hayır | string | US |
İki harfli ülke veya bölge kodu. Bkz. Desteklenen pazarlar. |
location |
Hayır | string | - | Biçimdeki lat:<latitude>;long:<longitude> konum, örneğin lat:37.7749;long:-122.4194. Enlem -90 ile 90 arasında, boylam ise -180 ile 180 arasında olmalıdır. |
Commerce Search yanıtı
Dereceli ürünleri ve tekliflerini içeren bir CommerceResponse döndürür. Hiçbir ürün eşleşmiyorsa, yanıt boş products bir diziyle olur200 OK.
Örnek 200 OK yanıt (alıntı):
{
"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>"
}
Ticaret Arama hataları
Eksik, boş veya uzun query, aralık maxResultsdışı , iki karakter olmayan bir language veya region geçersiz location bir döndürür 400 (HandlerInvalidInput ). Hizmet hataları () döndürür500InternalServerError. Kimlik doğrulaması, yetkilendirme, biçim ve kota hataları için bkz. Hatalar.
Ticaret Arama sınırları
-
query: 1 ile 1.000 karakter arasında ve yalnızca boşluk değil. -
maxResults: 1 - 50, varsayılan10. Döndürülen ürünlerin sayısı kullanılabilir eşleşmelere bağlıdır. Ürün başına teklif sayısı için sayfalandırma ve parametre yoktur. -
languageveregion: iki karakterli kodlar.locationkoordinatları parametreler tablosundaki aralıklar içinde olmalıdır. - Uygulama profilinizin (AppID) hız sınırları ve günlük kotası da geçerlidir.
Offers
Uç nokta:POST https://api.microsoft.ai/v3/fetch/commerce/products/offers
Ticari Arama'dan bir ürün, SKU veya temsili teklif için uygun satıcı tekliflerini döndürür. Ürün düzeyinde geri bildirim veya fiyat geçmişi yerine satıcı tekliflerini döndürür.
Örnek istek sunar
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"
}'
Parametreler sunar
Seçili ürün için tüm kullanılabilir ürün, SKU ve teklif tanımlayıcılarını Ticari Arama yanıtından gönderin. Yalnızca bir tanımlayıcı döndürülürse, bu tanımlayıcıyı gönderin. Boş olmayan en az bir tanımlayıcı gereklidir; tek bir istek döndürmeden (HandlerInvalidInput döndürür 400 .
| Parametre | Required | Type | Default | Description |
|---|---|---|---|---|
productId |
Conditional | string | - | Commerce Search tarafından döndürülen ürün id . En fazla 1.000 karakter. |
skuId |
Conditional | string | - | Commerce Search tarafından döndürülen ürün skuId . En fazla 1.000 karakter. |
offerId |
Conditional | string | - | Ticari Arama tarafından döndürülen temsili teklif id . En fazla 1.000 karakter. |
language |
Hayır | string | en |
İki harfli ISO 639-1 sonuç dili. Bkz. Desteklenen pazarlar. |
region |
Hayır | string | US |
İki harfli ülke veya bölge kodu. Bkz. Desteklenen pazarlar. |
location |
Hayır | string | - | Biçimli lat:<latitude>;long:<longitude> konum. Enlem -90 ile 90 arasında, boylam ise -180 ile 180 arasında olmalıdır. |
Yanıt sunar
CommerceOffersResponse
| Alan | Type | Description |
|---|---|---|
offers |
CommerceOffer dizisi | Birincil veya temsilci önce teklifler, ardından ek teklifler sunar. |
traceId |
string | Hata ayıklama ve bağıntı için istek izleme tanımlayıcısı. |
Teklif alanları için bkz. CommerceOffer, CommerceOfferImage, CommerceInstallmentInfo ve Destekleyici nesneler. Bilinmeyen tanımlayıcılar boş offers bir diziyle döner200 OK.
Örnek 200 OK yanıt (alıntı):
{
"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>"
}
Hatalar sunar
Eksik veya boş bir tanımlayıcı, 1.000 karakterden uzun bir tanımlayıcı, iki karakter olmayan bir language veya region veya geçersiz location bir dönüş 400 (HandlerInvalidInput ). Bilinmeyen tanımlayıcılar boş offers bir diziyle döner200 OK. Hizmet hataları () döndürür500InternalServerError. Bkz. Hatalar.
Sınırlar sunar
- İstek başına bir ürün, SKU veya temsili teklif araması; toplu aramalar desteklenmez. Her tanımlayıcı 1.000 karakterle sınırlıdır.
- , ofset veya imleç parametresi yoktur
maxResults. Tekliflerin sayısı kullanılabilirliğe bağlıdır. -
languageveregion: iki karakterli kodlar.locationkoordinatları parametreler tablosundaki aralıklar içinde olmalıdır. - Uygulama profilinizin (AppID) hız sınırları ve günlük kotası da geçerlidir.
Ürün Ayrıntıları
Uç nokta:POST https://api.microsoft.ai/v3/fetch/commerce/products/details
Ticari Arama'dan ürün kimliği, SKU kimliği veya her ikisi için ürün başlığını (name), açıklamasını ve toplam derecelendirmesini döndürür. Açıklama kullanılabilir olduğunda eklenir.
Ürün Ayrıntıları örnek isteği
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"
}'
Ürün Ayrıntıları parametreleri
En az bir productId veya skuId boş olmayan bir değer gereklidir ve her ikisini de gönderebilirsiniz.
offerId alternatif değildir: Yalnızca teklif kimliğine sahip bir istek doğrulanamadı.
| Parametre | Required | Type | Default | Description |
|---|---|---|---|---|
productId |
Conditional | string | - |
id Ticari Arama ürünü. Hayır skuId gönderildiğinde gereklidir. En fazla 1.000 karakter. |
skuId |
Conditional | string | - | Ticari Arama'dan SKU Kimliği. Hayır productId gönderildiğinde gereklidir. En fazla 1.000 karakter. |
language |
Hayır | string | en |
İki harfli dil kodu. veya nullbelirtilmezse, varsayılan kullanılır.
Bkz. Desteklenen pazarlar. |
region |
Hayır | string | US |
Ürün araması için iki harfli bölge kodu. veya nullbelirtilmezse, varsayılan kullanılır.
Bkz. Desteklenen pazarlar. |
Ürün Ayrıntıları yanıtı
CommerceProductDetailsResponse
| Alan | Type | Description |
|---|---|---|
products |
CommerceProductDetails dizisi | Sıfır veya eşleşen bir ürün. Toplu aramalar desteklenmez. |
traceId |
string | İstek izleme tanımlayıcısı. |
CommerceProductDetails
| Alan | Type | Description |
|---|---|---|
id |
string | Çeşitlemeler arasında ürün tanımlayıcısı, eşleşen Ticari Arama. |
name |
string | Ürün başlığı, kullanılabilir olduğunda. |
description |
string | Kullanılabilir olduğunda ürün açıklaması. |
rating |
CommerceRating | 1 ile 5 arasında bir ölçekte ürün ortalama derecelendirmesi ve derecelendirme sayısı. |
CommerceRating
Kullanılabilir rating derecelendirme olmadığında nesne atlanır.
| Alan | Type | Description |
|---|---|---|
value |
number | Ürün ortalaması derecelendirmesi, iki ondalık basameğe yuvarlanır. |
scaleMin |
number | Derecelendirme ölçeğinin (1) alt kısmı. |
scaleMax |
number | Derecelendirme ölçeğinin (5) üst kısmı. |
count |
integer | Ürünün derecelendirme sayısı. Sıfır sayısı olarak 0döndürülür. |
Bilinmeyen ürünler boş products bir diziyle geri döner200 OK.
Örnek 200 OK yanıt:
{
"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>"
}
Ürün Ayrıntıları hataları
Eksik veya boş bir ürün veya SKU tanımlayıcısı, 1.000 karakterden uzun bir tanımlayıcı veya iki karakter döndürmemiş bir language veya region (HandlerInvalidInput) döndürür 400 . Hizmet hataları () döndürür500InternalServerError. Bkz. Hatalar.
Ürün Ayrıntıları sınırları
- Her biri 1.000 karaktere kadar en az bir ürün veya SKU tanımlayıcısı. Yalnızca teklif kimliğine göre toplu aramalar ve aramalar desteklenmez.
-
languageveregion: iki karakterli kodlar. - Uygulama profilinizin (AppID) hız sınırları ve günlük kotası da geçerlidir.
Yanıt nesneleri
Bu nesneler Ticaret Arama ve Teklifler tarafından döndürülür.
CommerceResponse
| Alan | Type | Description |
|---|---|---|
products |
CommerceProduct dizisi | Derece sırasına göre ürünler. |
traceId |
string | Hata ayıklama ve bağıntı için istek izleme tanımlayıcısı. |
CommerceProduct
| Alan | Type | Description |
|---|---|---|
id |
string | Çeşitlemeler arasında ürün tanımlayıcısı. |
skuId |
string | Katalog SKU tanımlayıcısı. |
offers |
CommerceOffer dizisi | Birincil satıcı teklifleri. |
CommerceOffer
| Alan | Type | Description |
|---|---|---|
id |
string | Teklif tanımlayıcısı. |
name |
string | Satıcı başlığı. |
description |
string | Satıcı açıklaması. |
specifications |
dizisi CommerceSpecification |
Teklif düzeyi belirtimleri ve seçili öznitelikler. Yinelenenler ve kaynak sırası korunur. Bkz . Destekleyici nesneler. |
seller |
CommerceSeller |
Satıcı ayrıntıları. Bkz . Destekleyici nesneler. |
price |
CommerceOfferPrice |
ISO 4217 küçük birimlerde teklif fiyatlandırması.
offeredPrice indirim fiyatı olmadığında geri döner listPrice . Bkz . Destekleyici nesneler. |
displayUrl |
string | Yalnızca görüntüleme veya model bağlamı için satıcı veya satıcı URL'si. Bunu bağlantı veya gezinti hedefi olarak kullanmayın. |
clickUrl |
string | Teklife yönelik her bağlantı veya gezinti için hedef. Tam olarak döndürülen şekilde kullanın. Bkz . Teklif bağlantıları ve ilişkilendirme. |
images |
CommerceOfferImage dizisi | Resim teklif edin. |
installmentInfo |
CommerceInstallmentInfo | Taksit ödeme ayrıntıları. |
shippingInfo |
string | Okunabilir metin olarak sevkiyat bilgileri. |
condition |
string | Teklif edilen ürünün satıcı tarafından sağlanan koşulu. |
CommerceOfferImage
| Alan | Type | Description |
|---|---|---|
url |
string | Resim URL'si. |
CommerceInstallmentInfo
| Alan | Type | Description |
|---|---|---|
description |
string | Taksit planının okunabilir metin olarak açıklaması. |
downPayment |
CommercePrice |
Tutarın önde olması gerekir. Bkz . Destekleyici nesneler. |
monthlyPayment |
CommercePrice |
Aylık taksit ödemesi. Bkz . Destekleyici nesneler. |
months |
integer | Ay sayısı. |
Destekleyici nesneler
Fiyatlar, para biriminin ISO 4217 küçük birimlerindeki tamsayılardır. Örneğin, 10000 ile currencyUSD değeri 100,00 TL'dir.
| Object | Alan | Type | Description |
|---|---|---|---|
CommerceOfferPrice |
listPrice |
integer | ISO 4217 küçük birimler orijinal fiyat. |
CommerceOfferPrice |
offeredPrice |
integer | ISO 4217 küçük birimler güncel fiyat. İndirim fiyatı olmadığında geri listPrice döner. |
CommerceOfferPrice |
currency |
string | ISO 4217 para birimi kodu. |
CommercePrice |
amount |
integer | ISO 4217 küçük birim cinsinden ödeme tutarı. |
CommercePrice |
currency |
string | ISO 4217 para birimi kodu. |
CommerceSeller |
name |
string | Satıcı görünen adı. |
CommerceSeller |
logoUrl |
string | Satıcı logosu URL'si. |
CommerceSpecification |
name |
string | Teklif öznitelik adı. |
CommerceSpecification |
values |
dize dizisi | Yinelenenleri ve kaynak sırasını koruyarak öznitelik görüntüleme değerleri. |
Errors
Bu hatalar üç uç nokta için de geçerlidir. Her uç noktanın doğrulama ve boş sonuç davranışı kendi bölümünde açıklanmıştır.
| HTTP durumu | Hata kodu | Anlam ve eylem |
|---|---|---|
400 |
RequestInvalidFormat, HandlerInvalidInput |
Hatalı biçimlendirilmiş JSON veya eksik veya geçersiz istek parametreleri. Uç noktanın parametre tablosunu ve sınırlarını kullanarak isteği düzeltin. |
401 |
veya gibi AuthNoToken kimlik doğrulama hataları AuthInvalidApiKey |
Kimlik bilgileri eksik, geçersiz veya süresi dolmuş. Geçerli kimlik bilgileriyle yeniden kimlik doğrulaması. |
403 |
AuthUnauthorizedService |
Arayan, istenen kaynağa erişme yetkisine sahip değil. Uygulama profiliniz Commerce için etkinleştirilmemişse, bu sayfanın üst kısmında açıklandığı gibi erişim isteyin. |
405 |
MethodNotAllowed |
POST'yi, GET'ye tercih edin. |
415 |
RequestUnsupportedMediaType |
Gönderin content-type: application/json. |
429 |
AuthUserThrottled, AuthUserDailyUsageExceeded |
Uygulama profilinizin (AppID) hız sınırı veya günlük kotası aşıldı. Yeniden denemeden önce içindeki retryAfter süreyi bekleyin. |
500 |
InternalServerError |
Servis, talebi tamamlayamadı. Belirtilen gecikmeden sonra yeniden deneyin ve desteğe başvurduğunda öğesini traceId ekleyin. |
Hata yanıtı
Hatalar paylaşılan hata yanıt yapısını kullanır.
| Alan | Type | Description |
|---|---|---|
errorCode |
string | Makine tarafından okunabilir hata kodu. |
errorCategory |
string |
UserError veya SystemError. |
userMessage |
string | Hatanın okunabilir açıklaması. |
technicalDetails |
string | İsteğe bağlı tanılama ayrıntıları. |
retryAfter |
string | saniye olarak isteğe bağlı yeniden deneme gecikmesi ve ardından bir s sonek (örneğin, "60s"). |
requestId |
string | İsteğe bağlı istek tanımlayıcısı. |
traceId |
string | Destek için isteğe bağlı dağıtılmış izleme tanımlayıcısı. |
Hata örneği
olmadan querybir Ticaret Arama isteği:
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 yanıt:
{
"errorCode": "HandlerInvalidInput",
"errorCategory": "UserError",
"userMessage": "Invalid input provided. Please check your request parameters.",
"technicalDetails": "query is required",
"traceId": "<trace-id>"
}
Hız sınırları
Üç uç nokta da AppID'nin çağırdığı diğer Web IQ API'leriyle paylaşılan Web IQ AppID'nizin (varsayılan olarak saniyede 15 sorgu) hız sınırlarını ve günlük kotasını kullanır. Yanıt 429 , içindeki retryAfteryeniden deneme gecikmesini içerir. Günlük kotalar UTC saat 00:00'da sıfırlanır. Yeniden deneme kılavuzu için bkz. Hata işleme.