Aracılığıyla paylaş

Ürünlerinizi Yönetme

  • Makale

İçerik API'si, Microsoft Merchant Center (MMC) mağazanızdaki ürün tekliflerini yönetmek için Ürünler kaynağını kullanan bir RESTful API'dir.

aşağıda, İçerik API'sini çağırmak için kullandığınız temel URI'dir.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/

Her HTTP isteği kullanıcının OAuth erişim belirtecini ve geliştirici belirtecinizi içermelidir. Kullanıcının erişim belirtecini belirtmek için AuthenticationToken üst bilgisini ayarlayın. Geliştirici belirtecinizi belirtmek için DeveloperToken üst bilgisini ayarlayın.

Katalogları diğer müşteriler adına yönetiyorsanız şunları ayarlamanız gerekir:

  • Mağazasını yönettiğiniz müşterinin müşteri kimliğinin CustomerId üst bilgisi.
  • Yönettiğiniz müşteri hesaplarından herhangi birinin hesap kimliğinin CustomerAccountId üst bilgisi (yönetilen hesabın hangisi olduğu önemli değildir).

varsayılan olarak, İçerik API'sinde ürün teklifini temsil etmek için JSON nesneleri kullanılır. XML kullanmak için alternatif sorgu parametresini XML olarak ayarlayın.

Ürünler kaynağını kullanma hakkında ayrıntılı bilgi için aşağıdaki bölümlere bakın.

Mağazadan ürün teklifi alma

Mağazadan belirli bir ürün teklifi almak için aşağıdaki şablonu temel URI'ye ekleyin.

{mmcMerchantId}/products/{productUniqueId}

MMC mağaza kimliğiniz olarak ayarlayın {mmcMerchantId} ve ürünün offerId değerini değil, tam ürün kimliğini (örneğin, Online:en:US:Sku123) ayarlayın{productUniqueId}. Ürün kimliği büyük/küçük harfe duyarlı olduğundan, ürünü eklerken API'nin size döndürdiği kimliği kullanın.

Sonuçta elde edilen URL'ye bir HTTP GET isteği gönderin. Ürün bulunduysa, yanıt teklifi içeren bir Product nesnesi içerir.

Birden çok kataloğa aynı kimliğe sahip bir ürün eklediyseniz, hizmet bunlardan yalnızca birini döndürür; hangi ürün ve hangi katalogdan hangileri belirsizdir. Bu nedenle, birden çok kataloğa aynı ürün kimliğine sahip bir ürün eklememelisiniz.

Bir ürün teklifinin nasıl alındığını gösteren bir kod örneği için bkz. Ürün Kodunu Yönetme Örneği.

Mağazadan ürün tekliflerinin listesini alma

Mağazada bulunan ürün tekliflerinin listesini almak için aşağıdaki şablonu temel URI'ye ekleyin.

{mmcMerchantId}/products

MMC mağaza kimliğiniz olarak ayarlayın {mmcMerchantId} .

Teklif listesinde sayfalandırmak için max-results ve start-token sorgu parametrelerini kullanın. İlk aramanızda, hizmetin döndürmesini istediğiniz teklif sayısı üst sınırına ayarlayın max-results . Hizmetin döndürebileceği teklif sayısı üst sınırı 250'dir. Varsayılan değer 25'tir. Sonuçta elde edilen URL'ye bir HTTP GET isteği gönderin. Aşağıda isteğin bir örneği gösterilmektedir.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250

Depo teklifler içeriyorsa, yanıt istenen teklif sayısına kadar içeren bir Product nesnesi içerir.

Daha fazla teklif varsa, yanıt alanını nextPageToken içerir (bkz . Ürünler). alanı, nextPageToken sonraki Liste isteğinizde parametresini olarak ayarlamak start-token için kullandığınız belirteç değerini içerir. Aşağıda belirteci kullanan bir örnek gösterilmektedir.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250&start-token=DFSos893j...

Ürün tekliflerinin listesinin nasıl alındığını gösteren bir kod örneği için bkz. Ürün Kodunu Yönetme Örneği.

Mağazadan bir teklifi silme

Mağazadan belirli bir ürün teklifini silmek için aşağıdaki şablonu temel URI'ye ekleyin.

{mmcMerchantId}/products/{productUniqueId}

MMC mağaza kimliğiniz olarak ayarlayın {mmcMerchantId} ve ürünün offerId değerini değil, tam ürün kimliğini (örneğin, Online:en:US:Sku123) ayarlayın{productUniqueId}. Ürün kimliği büyük/küçük harfe duyarlı olduğundan, ürünü eklerken API'nin size döndürdiği kimliği kullanın.

Sonuçta elde edilen URL'ye bir HTTP DELETE isteği gönderin. Ürün bulunduysa silinir.

Birden çok kataloğa aynı ürün kimliğine sahip bir ürün eklediyseniz, hizmet bunların tümünü siler. Aynı ürün kimliğine sahip bir ürünü birden çok kataloğa eklememelisiniz.

Bir ürün teklifinin nasıl silindiğini gösteren bir kod örneği için bkz. Ürün Kodunu Yönetme Örneği.

Ürün teklifi ekleme ve güncelleştirme

Teklif ekleme veya güncelleştirme bir ekleme işlemidir. Güncelleştirme bir ekleme işlemi olduğundan, teklifin tüm alanlarını isteğe eklemeniz gerekir; tek bir alanı güncelleştiremezsiniz.

Ürün teklifi eklemek için aşağıdaki şablonu temel URI'ye ekleyin.

{mmcMerchantId}/products

MMC mağaza kimliğiniz olarak ayarlayın {mmcMerchantId} .

Sonuçta elde edilen URL'ye BIR HTTP POST isteği gönderildiğinde, teklif varsayılan depo kataloğuna yazılır. Teklifi belirli bir kataloğa yazmak için bmc-catalog-id sorgu parametresini ekleyin.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?bmc-catalog-id=123456

Ürün eklendiyse, yanıt bir Product nesnesi içerir. Product nesnesi, teklifi almak ve silmek için kullandığınız ürün kimliğini içerir.

Teklif aşağıdaki alanları içermelidir:

API, ürün kimliğini oluşturmak için , contentLanguage, targetCountryve offerId kullanırchannel. Bu alanlar kimliği oluşturmak için kullanıldığından, bunları güncelleştiremeyebilirsiniz. Ürün kimliği büyük/küçük harfe duyarlıdır; kimlik, contentLanguagetargetCountryve offerIdbelirtmek channeliçin kullandığınız büyük/küçük harfle aynı büyük/küçük harf kullanır.

Dikkat

Büyük/küçük harf farklıysa aynı ürünü birden çok kez etkili bir şekilde ekleyebildiğiniz için , contentLanguage, targetCountryve offerId için channelde aynı büyük/küçük harf kullandığınızdan emin olun.

Üretici tarafından değerler atandıysa aşağıdaki alanlar da gereklidir.

Biliniyorsa değerleri belirtmeniz gerekir. Bunlardan hiçbirini belirtmezseniz identifierExists alanını false olarak ayarlamanız gerekir. Varsayılan değer true'dur.

Ürünün bu tanımlayıcılara sahip olduğu biliniyorsa ve bunları belirtmezseniz MMC ürünü şimdilik kabul eder, ancak yanıttaki Product nesne alanı içerir warnings . Alanın var olup olmadığını warnings her zaman denetlemeniz ve tanımlanan tüm sorunları düzeltmeniz gerekir.

Gerekli alanlara ek olarak, teklifin süresinin dolmasını istediğiniz tarih ve saati de belirtmeniz gerekir (bkz . expirationDate). Varsayılan olarak, teklifin süresi mağazaya veya kataloğa yazıldıktan sonra 30 gün sonra dolar. Süresi dolmak üzere olan ve süresi dolmadan önce ürünleri izlemeniz veya ürünü güncelleştirmeniz yeterlidir (ürün alanlarından herhangi birini güncelleştirmeniz gerekmez), bu da son kullanma tarihini otomatik olarak 30 gün daha uzatır. Son kullanma tarihini açıkça ayarlarsanız, kendiniz yeni bir sona erme tarihi ayarlamanız gerekir; ürünün güncelleştirilmesi, bu durumda son kullanma tarihini otomatik olarak 30 gün daha uzatmaz.

Diğer tüm alanlar isteğe bağlı olarak kabul edilir; ancak, ürünü doğru bir şekilde tanımlamak için gerekenlerin sayısını belirtmeniz gerekir.

Not

Product Nesnesi yalnızca değerlere ayarlanmış alanları içermelidir. Nesneye null alanlar eklemeyin Product . Örneğin, eklemeyin "adult":null.

Microsoft tüm Product alanları kullanmaz. API'nin kabul ettiğini ancak kullanmadığı alanların listesi için bkz . Hangi Google özniteliklerini kullanabilirim? Microsoft tarafından kullanılan diğer tüm alanlar, ürün reklamları sunarken ürünleri filtrelemek için kullanılır.

İçerik API'sinde bilinmeyen bir alan belirtirseniz, hizmet alanı yoksayar.

Bir teklif eklediğinizde, hizmet teklifte temel doğrulamalar gerçekleştirir ve hataları ve uyarıları uygun şekilde döndürür. Bir hata oluşursa, yanıt bir ErrorResponse nesne içerir. Uyarı oluşursa, yanıt bir Product nesne içerir ve warnings alan uyarıları listeler.

Teklif temel doğrulamaları geçerse, 36 saate kadar sürebilecek çevrimdışı doğrulamalardan ve editör incelemeleri gibi incelemelerden geçer. Tüm doğrulamalar ve incelemeler tamamlanana kadar teklif sunulmaz. Teklifin durumunu belirlemek için Durum kaynağını kullanın.

API'nin ETag'ler gibi eşzamanlılık denetimleri sağlamadığını unutmayın. aynı ürünü eklemeye veya güncelleştirmeye çalışan iki uygulama varsa, sonuncusu kazanır.

Bir ürün reklamında görüntülenen teklif fiyat, başlık, mağaza adı (veya belirtilirse sellerName), ürün hakkında daha fazla bilgi içeren web sayfasının bağlantısını ve ürünün görüntüsünü içerir.

Birden çok renk, desen veya malzemede bulunan hazır giyim ürünleri için her çeşit için bir ürün oluşturun ve tüm ürün çeşitlemelerini gruplandırmak için itemGroupId alanını kullanın.

Ürün teklifinin nasıl eklendiğini gösteren bir kod örneği için bkz. Ürün Kodunu Yönetme Örneği.

Toplu işlemeyi kullanma

Birden çok ürün teklifi işliyorsanız API'nin toplu işleme özelliğini kullanmayı düşünmelisiniz. Bu özellik, tek bir istekte birden çok ekleme, alır ve silme işlemlerini gerçekleştirmenize olanak tanır. Aynı istekte birden çok teklifi işlemek, her teklif için ayrı bir istek göndermekten daha verimlidir. Tek bir isteğin işlenmesiyle tahakkuk eden maliyet, her bir istek için bu maliyetin yansıtılması yerine toplu istekteki binlerce teklife yayılır.

Aynı isteğe aynı ürünü eklemeyin, almayın veya silmeyin.

Toplu istek göndermek için aşağıdaki şablonu temel URI'ye ekleyin.

{mmcMerchantId}/products/batch

MMC mağaza kimliğiniz olarak ayarlayın {mmcMerchantId} .

Sonuçta elde edilen URL'ye HTTP POST isteği göndermek, ekleme işlemlerini varsayılan depo kataloğuna uygular. Teklifleri belirli bir kataloğa uygulamak için bmc-catalog-id sorgu parametresini ekleyin.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products/batch?bmc-catalog-id=123456

POST'un gövdesi, bir Öğe nesneleri dizisi içeren bir Batch nesnesidir. Tüm işlemler için , merchantId ve method alanlarını ayarlayınbatchId. batchId, yanıttaki toplu iş öğesini tanımlamak için kullandığınız kullanıcı tanımlı bir kimliktir; merchantId mağaza kimliğiniz method ve gerçekleştirilecek işlemdir (örneğin, ekleme, silme veya alma).

method Ekle ise, alanı ekleme veya güncelleştirme teklifini içeren bir Product nesnesi olarak ayarlayınproduct. Aksi takdirde, method alma veya silme ise, almak veya silmek istediğiniz teklifin tam kimliğine ayarlayınproductId.

Toplu iş isteğinin gövdesinin boyutu 4 MB'ı aşamaz. Gövde 4 MB'ı aşarsa, yanıt HTTP durum kodu 413'ü döndürür. Her teklifin boyutuna (belirttiğiniz alan sayısına) bağlı olarak, 2.000 ile 6.000 arasında teklif gönderebilirsiniz. Gövdeyi sıkıştırırsanız, en fazla 12.000 teklif gönderebilirsiniz (boyutlarına bağlı olarak).

Gövdeyi sıkıştırmak için yalnızca GZip sıkıştırmasını kullanın ve isteğin Content-Encoding üst bilgisini gzip olarak ayarlayın.

Hizmet, toplu iş içindeki her öğeyi işler. Yanıt, istekteki her Item bir nesneyi içeren bir Batch nesne içerir. Yanıttaki öğelerin sırasının istekteki öğelerle aynı sırada olduğunu garanti etmediğini unutmayın.

Ekleme işlemleri için öğe yalnızca batchId ve product alanlarını içerir. Bu product alan, istekte gönderdiğiniz teklifin aynısını içerir, aynı zamanda tam ürün kimliğini de içerir. Bir hata veya uyarı oluşursa, öğe , methodve error alanlarını içerirbatchId. Alanı error , ekleme işleminin başarısız olmasının nedenlerini veya düzeltmeniz gereken teklifle ilgili sorunlar hakkında uyarıları içerir.

Alma işlemleri için öğe ve product alanlarını içerirbatchId. Alanı product , istediğiniz teklifi içerir. Ürün bulunamazsa nesne alanı içermez product .

Silme işlemleri için, öğe yalnızca batchId alanı içerir; teklifin mevcut olup olmadığının ve silinip silinmediğinin göstergesi yoktur.

Toplu işlemenin nasıl kullanılacağını gösteren bir kod örneği için bkz. Batch İsteği Oluşturma.