Ticaret API'leri ile alışveriş deneyimi oluşturma (özel önizleme)

Microsoft Web IQ Ticaret API'leri, uygulamanızın bir alışveriş deneyimini temel almak için kullanabileceği yapılandırılmış ürünleri, satıcı tekliflerini ve ürün ayrıntılarını döndürür. Uygulamanız, bir alışverişçinin isteğini yorumlamak ve ürün seçimlerini açıklamak için bir yapay zeka modeli kullanabilir, ancak fiyatları, satıcıları ve bağlantıları oluşturmak yerine API sonuçlarından görüntüler.

Note

Ticaret API'leri özel önizleme aşamasındadır ve tam belge erişimine sahip AppID'lerle sunulur. Arama, Teklifler ve Ürün Ayrıntıları için erişim ayrı ayrı etkinleştirilir: Tek başına arama erişimi izleme uç noktalarına erişim vermez. AppID'nizde yoksa, AppID'nizle bir Web IQ Destek isteği (sorun türü Kimlik Doğrulaması ve Erişim) açın. İlk aramalarınızı yapmak için Hızlı Başlangıç'ın 8. adımına bakın.

Uç nokta seçme

Müşteri sorusu Endpoint Input Result
Hangi ürünler eşleşiyor? POST /v3/search/commerce/products Ürün sorgusu Sıralandı products birincil satıcı offers ile
Bunu nereden alabilirim? POST /v3/fetch/commerce/products/offers Ürün, SKU veya temsili teklif kimliği Uygun satıcı offers, temsilci teklifleri önce
Ürün ayrıntıları nelerdir? POST /v3/fetch/commerce/products/details Ürün veya SKU Kimliği Kullanılabilir olduğunda ad, açıklama ve toplam derecelendirmesi olan sıfır veya bir ürün

Yollar, https://api.microsoft.ai öğesine göreli. Her uç nokta bir JSON gövdesi ve Commerce için etkinleştirilmiş bir API anahtarı veya Microsoft Entra ID belirteci alır; bkz. Kimlik doğrulaması. Yalnızca Ara'yı kullanabilir ve gerektiğinde Teklifler veya Ürün Ayrıntıları'nı çağırabilirsiniz.

Çağrıları bağlayın

  1. Search'e kısa bir alışverişçi sorgusu gönderin ve döndürülen ürünlerden birini seçin.
  2. Teklifler için, sonucun içerdiği tüm tanımlayıcıları gönderin: ürünü id olarak productId, skuId öğesini skuId olarak ve temsilî teklifinin id öğesini offerId olarak gönderin. Aynı sonuçtaki ID'leri kullanın. En az bir tane gereklidir.
  3. Ürün Ayrıntıları için ürün id değerini skuId, productId veya her ikisi olarak gönderin.
  4. Boş offers veya 200 OK dizisi içeren products değerini, başarısız bir istek olarak değil, eşleşme yok olarak değerlendirin. İzleme istekleri tek seferde bir ürün, SKU veya temsili teklif üzerinde çalışır; bu uç noktalar toplu kimlikleri veya sayfalandırmayı desteklemez.

Tanımlayıcıları opak dizeler olarak değerlendirin. Arama sonucu her kimliği içermeyebilir: bazı ürünler yalnızca bir offer döndürür. Yalnızca bir teklif kimliği varsa Teklifler'i isteyebilirsiniz ancak Ürün Ayrıntıları'nı talep edemezsiniz. Kimliğin zaman içinde geçerli kalacağını veya birkaç kimlik gönderdiğinizde bir kimliğin öncelikli olduğunu varsaymayın.

Pazarı seçin

Üç uç noktanın tümü, varsayılan değerler olarak language ve region ile birlikte iki karakterli US ve en değerlerini kabul eder. Özel önizlemede kullanılabilen birleşimler için desteklenen pazarlar bölümüne bakın. Arama ve Teklifler de, -90 ile 90 arasında enlem ve -180 ile 180 arasında boylam içeren, location biçiminde isteğe bağlı bir lat:<latitude>;long:<longitude> kabul eder. Ürün Ayrıntıları bir locationalmaz.

Alışveriş yapanın seçtiği pazarı çağrılar arasında tutarlı bir şekilde kullanın. Konum veya diğer kişisel bağlamı yalnızca uygulamanızın bunu yapma yetkisi olduğunda gönderin. Katalog kapsamı pazara göre değişir.

Sonuç sayısını denetleme

Arama maxResults, varsayılan değeri 10 olan 1 ile 50 ürün ister; teklif sayısını ayarlamaz. Sonuçları doğrudan bir modele gönderdiğinizde daha küçük bir sonuç kümesi yararlı olabilir. Uygulamanız sonuçları önce filtrelediğinde veya sıraladığında daha büyük bir aday kümesi yararlı olabilir. Arama, istenenden daha az ürün döndürebilir.

Tekliflerde maxResults, ofset veya imleç yoktur; tekliflerin sayısı kullanılabilirliğe bağlıdır. Ürün Ayrıntıları en fazla bir ürün döndürür.

Bir ajan aracı oluşturun

Bir yaklaşım, Search aracını bir araç olarak sunmak ve pazar ayarlarını güvenilir uygulama kodunda tutmaktır. Aşağıda Web IQ uç noktası değil, açıklayıcı bir araç şeması bulunur:

{
  "name": "search_products",
  "description": "Find ranked products and seller offers for a shopping request.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "A nonblank product query of at most 1000 characters."
      },
      "maxResults": {
        "type": "integer",
        "minimum": 1,
        "maximum": 50,
        "description": "Maximum number of products to request; default 10."
      }
    },
    "required": ["query"]
  }
}

Araç işleyiciniz modelin bağımsız değişkenlerini doğrulamalı, kullanıcının seçili language ve region değerlerini eklemeli ve Search'ü sunucu tarafı kimlik bilgileriyle çağırmalıdır. Arama, en fazla 1.000 karakterden oluşan boş olmayan bir sorguyu kabul eder. Birkaç farklı ürün türü içeren bir istek için, tür başına ayrı bir Arama çağrısı düşünün ve eşzamanlılık ile istek hacmini sınırlayın: her çağrı AppID'nizin hız sınırına ve kotasına göre sayılır.

Modele döndürülen alanlardan derli toplu bir seçki verin ve izleme çağrıları için ihtiyacınız olan kimlikleri koruyun. Satıcı başlıklarını, açıklamalarını ve döndürülen diğer metinleri yönergeler değil güvenilmeyen veriler olarak değerlendirin. Modelin satın alma URL'leri oluşturmasına veya API döndürmediğinde bir ürün, fiyat veya derecelendirme olduğunu iddia etmesine izin vermeyin.

Sonuçları filtreleme, sıralama ve görüntüleme

  1. Uygulama kodundaki katı kısıtlamaları denetleyin. Alışveriş yapan kişi maksimum fiyat, koşul, boyut veya diğer öznitelikleri belirtiyorsa, eşleşme göstermeden önce kullanılabilir teklif verilerini denetleyin. Gerekli bir alan eksikse veya yorumlanamazsa kısıtlamanın karşılandığını iddia etmeyin. Teklif specifications , marka veya boyut gibi öznitelikleri içerebilir, ancak kullanılabilirlik ve değerler farklılık gösterir.
  2. Adayları derece sırasına göre belirleyin. Search product rank ile başlayın, ardından uygulamanızın ölçütlerini uygulayın. Modeli yeniden sıralamak için kullanıyorsanız, yalnızca göz önünde bulundurmasını istediğiniz adayları gönderin ve özgün yapılandırılmış verileri işleme için saklayın.
  3. Benzer olanları birbiriyle karşılaştırın. Satıcı karşılaştırmaları için ürünü ve varyantı, para birimini ve koşulu denetleyin. Liste görüntülemeden önce yinelenen teklif kimliklerini kaldırın ve en düşük fiyatı talep etmeden önce teklifleri doğrulayın.
  4. Alanlardan oluşturun. Teklifi name, seller.name, price, condition, shippingInfo ve images[].url mevcut olduğunda kullanın. Sunduğun her teklif için bu yanıttan onun clickUrl öğesine bağlantı ver. displayUrl öğesini yalnızca görüntüde tüccarı veya satıcıyı tanımlamak için kullanın, hedef olarak değil. Bkz. Teklifler bağlantısı.
  5. Sorun durumunda zarifçe bozulmalıdır. Model adımı başarısız olursa, uygun olduğunda açıklama oluşturulmadan mevcut yapılandırılmış sonuçları gösterin. Bir Ticaret isteği başarısız olursa, ürün veya fiyatlar uydurmak yerine sonuçların kullanılamadığını belirtin ve yeniden denemeyi önerin.

Ürün Ayrıntıları bir ürün name, descriptionve toplam ratingdöndürebilir. Derecelendirme, mevcut olmadığında atlanır. value, scaleMin, scaleMax ve count, tek bir teklifi veya belirli bir varyantı değil, ürünü tanımlar. Değerlendirme metnini veya değerlendirme özetini toplam derecelendirmeden çıkarmayın.

Sunduğunuz her teklif için, bir kullanıcıyı veya kullanıcı adına hareket eden bir aracıyı teklife göndermek üzere, teklifin clickUrl öğesini tam olarak bu yanıtta döndürüldüğü şekilde kullanın. displayUrl yalnızca ekranınızdaki tüccarı veya satıcıyı tanımlamak ya da bir model için bağlam olarak kullanın; asla gezinme için kullanmayın. Bir teklifin kullanılabilir bir clickUrl sürümü yoksa teklifi sunmayın; displayUrl öğesine geri dönmeyin veya bir bağlantı oluşturmayın.

clickUrl öğesini opak kabul edin: önbellek aracılığıyla da dahil olmak üzere, onu kaldırmayın, yeniden yazmayın, kesmeyin, çözümlemeyin veya değiştirmeyin; yeniden yönlendirmelerini atlamayın ve farklı bir yanıt, sorgu, kullanıcı veya amaç için yeniden kullanmayın. clickUrl öğesini kendi izleme bağlantınıza ne zaman sarabileceğiniz de dahil olmak üzere tam kurallar için, Commerce referansındaki Teklif bağlantıları ve ilişkilendirme bölümüne ve Web IQ Kullanım Koşulları'nın Ek B'sine bkz.

Modelde değil kodda gezinti oluşturma

Her özgün clickUrl öğesini, teklifi, yanıtı ve kullanıcısıyla ilişkili güvenilir uygulama kodunda tutun. Modele, ilgili ürün bilgileriyle birlikte uygulamanızın bu yanıt için oluşturduğu bir teklif tanıtıcısı gönderin. Model bir tanıtıcı seçebilir, ancak bağlantıyı yeniden oluşturmamalı veya değiştirmemelidir. İşleme veya gezinme sırasında tanıtıcıyı özgün yanıta karşı çözümleyin ve modelin oluşturduğu URL'ye geri dönmek yerine bilinmeyen veya eski tanıtıcıları reddedin. Bir aracının clickUrl alması gerekiyorsa, tam özgün değeri aldığından ve kullandığından emin olun.

Aşağıdaki tarayıcı örneği, geçerli yanıttaki bir teklif nesnesinden bağlantı oluşturur. Muhafazakar bir uygulama ilkesi olarak, yalnızca HTTPS bağlantılarını kabul eder ve tarayıcının URL ayrıştırıcısının veya bağlantı serileştirmesinin değiştireceği değerleri reddeder. Yeniden yapılandırılmış URL'yi değil özgün dizeyi atar. döndürdüğünde nullbu teklifi sunmayın. Bunu bir tarayıcı konsolunda çalıştırabilirsiniz; son denetim, URL'nin korunduğunu ve eksik veya güvenli olmayan hedeflerin reddedildiğini onaylar.

function createOfferLink(offer) {
  if (typeof offer.clickUrl !== "string" || offer.clickUrl.length === 0) {
    return null;
  }
  try {
    const parsed = new URL(offer.clickUrl);
    if (parsed.protocol !== "https:" || parsed.href !== offer.clickUrl) return null;
  } catch {
    return null;
  }

  const link = document.createElement("a");
  link.setAttribute("href", offer.clickUrl);
  if (link.href !== offer.clickUrl) return null;
  link.textContent = offer.name || "View offer";
  return link;
}

const exampleClickUrl = "https://merchant.example/offer?attribution=opaque%2Fvalue";
const exampleLink = createOfferLink({ clickUrl: exampleClickUrl, name: "Example offer" });
if (
  exampleLink?.getAttribute("href") !== exampleClickUrl ||
  createOfferLink({ clickUrl: "javascript:alert(1)" }) !== null ||
  createOfferLink({ displayUrl: "https://merchant.example/products/headphones" }) !== null
) {
  throw new Error("Offer links must preserve clickUrl without a fallback.");
}

Bu denetim, yolun ilerleyen kısımlarındaki yönlendirmeleri veya sarmalayıcıları doğrulamaz; uygulamanızda gezinti yolunun tamamını test edin. Hedef olarak model tarafından oluşturulan alıntı, Markdown bağlantısı veya displayUrl kullanmayın.

Fiyatları biçimlendirme

listPrice, offeredPriceve taksit miktarları ISO 4217 ikincil birimlerindeki tamsayılardır. ABD doları iki ondalık basamak kullandığı için 39999 399,99 ABD dolarıdır; JPY sıfır kullanır. 100'e sabit bir bölme değil, para biriminin kendi ikincil birim ölçeğini kullanın. offeredPrice, indirim fiyatı olmadığında listPrice değerine geri döner. Bir liste fiyatını önceki fiyat olarak yalnızca teklif edilen fiyattan daha büyükse ve geçerli koşullar buna izin verirse gösterin.

Örneğin, bu JavaScript biçimlendiricisi üç para birimini açıkça işler:

function formatPrice(amount, currency, locale = "en-US") {
  const minorUnitDigits = { USD: 2, JPY: 0, KWD: 3 };
  const digits = minorUnitDigits[currency];
  if (!Number.isSafeInteger(amount) || digits === undefined) {
    throw new Error("Unsupported currency or unsafe integer amount");
  }
  const formatter = new Intl.NumberFormat(locale, {
    style: "currency",
    currency,
    minimumFractionDigits: digits,
    maximumFractionDigits: digits,
  });
  return formatter.format(amount / 10 ** digits);
}

console.log(formatPrice(39999, "USD")); // $399.99 in en-US

Üretimde, ölçeği görüntü varsayılanlarından Intl çıkarsamak yerine uygulamanızın desteklediği her para birimi için bakımlı bir ISO 4217 ikincil birim tablosu kullanın. Dönüştürme ilkesi olmadan para birimleri arasındaki tutarları karşılaştırmayın. Fiyatlar ve kullanılabilirlik değişir, bu nedenle bunları geçerli yanıttan görüntüleyin.

Hataları ve hız sınırlarını işleme

Üç uç nokta da AppID çağrılarının diğer Web IQ API'leriyle paylaşılan AppID'nizin hız sınırlarını ve günlük kotasını (varsayılan olarak saniyede 15 sorgu) kullanır. Oran ve kota hataları 429 döndürür; yanıttaki errorCode ve retryAfter değerlerini denetleyin.

Response Önerilen eylem
400, 401, 403veya 415 İsteği, kimlik bilgilerini veya erişimi düzeltin. Değişmemiş bir isteği yeniden denemek işe yaramaz.
429 AuthUserThrottled retryAfter süresi mevcutsa en az bu süre kadar bekleyin, ardından sınırlanmış üstel geri çekilme ve rastgele gecikme değişimi ile yeniden deneyin. İstek sıklığını azaltın.
429 AuthUserDailyUsageExceeded Yeniden denemeyin; günlük kota 00:00 UTC'de sıfırlanır.
500 InternalServerError Yönergeleri retryAfter izleyin ve sınırlı backoff ve jitter ile yeniden deneyin. Hatalar devam ederse Web IQ Desteği'ne başvurun.

Ticaret hataları için, retryAfter mevcut olduğunda "60s" gibi bir süredir. Zaman aşımı ve genel bir yeniden deneme bütçesi kullanın. Uç noktayı, durumu, hata kodunu ve traceId günlüğe kaydedip ihtiyacınız olmayan kimlik bilgilerini veya müşteri verilerini günlüğe kaydetmekten kaçının. Hata işleme bölümüne bakınız.

Başlatmadan önce test edin

  • Desteklediğiniz kategoriler ve pazarlar için temsili bir alışverişçi sorgusu kümesi oluşturun.
  • Kendi filtreleme ve derecelendirmenizi uygulamadan önce ham Arama sonuçlarını inceleyin ve ardından son deneyimi karşılaştırın.
  • Döndürülen ürünlerin, satıcı bağlantılarının, fiyatların ve koşulların bir örneğini, bunlar hakkında iddiada bulunmadan önce satıcı sayfalarına göre kontrol edin.
  • Kullanıcı ve ajan gezinmesinin, kendi sarmalayıcınız üzerinden geçse bile, ilgili yanıttaki tam clickUrl değerini kullandığını, yeniden yönlendirmelerin korunduğunu ve bağlantıların başka bir yanıt, sorgu, kullanıcı veya amaç için yeniden kullanılmadığını denetleyin.
  • Eksik veya kullanılamaz clickUrl değerlerini ve model tarafından oluşturulan veya eski teklif tanıtıcılarını test edin ve bunların hiçbirinin displayUrl veya oluşturulmuş bir bağlantıya geri dönmediğinden emin olun.
  • Boş sonuçları, eksik alanları, ürün veya SKU kimliği olmayan ürünleri, zaman aşımlarını, azaltmayı, kota tükenmesini ve model hatalarını test edin.
  • İstek hacmini, hataları ve izleme kimliklerini izleyin. Web IQ Desteği'ne başvurarak ilgili izleme kimliğini ekleyin.

Sonraki Adımlar