Dosya feed'leri ile Merchant API arasında seçim yapma

Ürün verilerini Merchant Center'a dosya tabanlı feed'ler, Merchant API veya her ikisinin bir kombinasyonunu kullanarak yükleyebilirsiniz:

  • Dosya tabanlı ürün feed'leri: SFTP, Google Cloud Storage, Google E-Tablolar veya planlı getirmeler aracılığıyla CSV, TSV ya da XML dosyaları yükleyin.
  • Merchant API: Ürün verileri değiştikçe artımlı güncellemeler için doğrudan arka ucunuzdan programatik istekler gönderin ve düzenli olarak tam katalog senkronizasyonları gerçekleştirin.

Bu kılavuzda her iki yaklaşım karşılaştırılmakta, birinin diğerine (veya her ikisine birden) ne zaman tercih edileceği açıklanmakta ve ürünlerinizin bir kısmını veya tamamını dosya feed'lerinden API'ye taşımaya karar verirseniz adım adım geçiş kılavuzu sunulmaktadır.

Veri kaynağı yaklaşımınızı seçme

Merchant API, dosya feed'leri veya karma bir kurulum kullanıp kullanmayacağınıza karar vermek için kataloğunuzun değişkenliğini, arka uç mimarinizi ve operasyonel iş akışlarınızı değerlendirin.

Merchant API ne zaman kullanılır?

Aşağıdaki durumlarda API birincil veri kaynağı kullanın:

  • Doğrudan programatik entegrasyon: Dosya oluşturmak ve dosya aktarım ardışık düzenlerini (ör. SFTP veya Google Cloud Storage) yönetmek yerine doğrudan arka ucunuzdan bir API çağırmayı tercih ediyorsanız.
  • Yüksek fiyat ve envanter dalgalanması: Ürün fiyatlarınız veya stok seviyeleriniz gün içinde sık sık değişiyor.
  • Veriler değiştiğinde anında güncelleme: Ürün değişikliklerini, bir sonraki planlı dosya oluşturma ve yükleme işlemini beklemek yerine arka uçta gerçekleşir gerçekleşmez Google'a göndermek istiyorsunuz.
  • Artımlı katalog güncellemeleri: Her seferinde tüm kataloğunuzu yeniden yüklemeden, değişen ürünleri tek tek eklemek, güncellemek veya silmek istiyorsunuz.
  • Kısmi özellik güncellemeleri: Ürünün tüm verilerini yeniden göndermeden belirli alanlarını (ör. productInputs.patch kullanarak price veya availability) güncellemek istiyorsunuz.

Dosya feed'leri ne zaman kullanılır?

Aşağıdaki durumlarda dosya tabanlı birincil veri kaynağı kullanın:

  • Statik katalog: Ürün verileriniz nadiren değişir (ör. günde bir kez veya daha az).
  • Delta izleme olmadan yalnızca anlık görüntü arka ucu: Arka ucunuz yalnızca tam katalog anlık görüntülerini dışa aktarır ve öğe düzeyindeki değişiklikleri veya açık ürün silme işlemlerini izleyemez.
  • E-tablo tabanlı iş akışları: Mühendislik dışı ekipler, ürün verilerini doğrudan Google E-Tablolar veya CSV dosyalarında düzenler ya da geçersiz kılar.
  • Az bakım gerektiren işlemler: İstek hızı, yeniden deneme işlemleri ve periyodik tam katalog senkronizasyonları ile bir API entegrasyonu çalıştırmak yerine Merchant Center'ın getirme ve anlık görüntü işlemlerini gerçekleştirdiği planlanmış bir dosya dışa aktarma işlemini tercih edersiniz.

İkisini de ne zaman kullanmalısınız?

Aşağıdaki senaryolarda dosya feed'lerini ve Merchant API'yi aynı Merchant Center hesabında birleştirebilirsiniz:

  • Bölümlere ayrılmış ürün katalogları: Hızlı değişen ürünler (ör. kısa süreli indirimler veya yüksek devirli envanter) için Merchant API'yi, statik katalog segmentleri veya ayrı ürün serileri için dosya feed'lerini kullanırsınız. Her ürünün yalnızca bir birincil veri kaynağı tarafından yüklendiğinden emin olun (Paralel kullanım ve birincil veri kaynağı sahipliği bölümüne bakın).
  • Dosya tabanlı ek feed'ler içeren API birincil verileri: Temel ürün verilerini bir API birincil veri kaynağı aracılığıyla yönetirsiniz. Mühendislik dışı ekipler veya üçüncü taraf iş ortakları ise özellik kurallarıyla birleştirilmiş dosya tabanlı ek feed'ler (ör. Google E-Tablolar veya CSV dosyaları) aracılığıyla ek özellikler sağlar ya da tam tersi şekilde çalışır.
  • Kısmi veya aşamalı taşıma: Kataloğunuzun geri kalanını dosya feed'lerinde tutarken belirli pazarları, kategorileri veya alt hesapları API'ye taşırsınız.

Ürünlerinizin bir kısmını veya tamamını dosya feed'lerinden Merchant API'ye taşımaya karar verirseniz Adım adım geçiş kılavuzunu uygulayın.

Temel mimari farklılıklar

Dosya feed'leri ve push tabanlı Merchant API, Google'ın ürün verilerini işleme ve yönetme şekli açısından farklılık gösterir:

Kavram Dosya Feed'leri Merchant API
Entegrasyon Modeli Çevrimdışı dosya dökümü: Kataloğunuzu bir dosyaya aktarır ve SFTP, Google Cloud Storage, Google E-Tablolar veya planlı getirmeler kullanarak aktarırsınız. Doğrudan programatik entegrasyon: Arka ucunuz, istekleri doğrudan API uç noktasına gönderir.
Mutasyon ayrıntı düzeyi Toplu işleme: Bir öğeyi değiştirmek genellikle tüm dosyanın yeniden işlenmesini gerektirir. Ayrıntılı işlemler: Yalnızca değişen ürünleri ekleyebilir, yamalayabilir veya silebilirsiniz.
Senkronizasyon Zamanlaması Toplu senkronizasyon: Değişiklikler, bir sonraki planlanmış dosya dışa aktarma ve aktarım döngüsüne kadar arka ucunuzda bekler. Anında veya planlanmış çağrılar: Artımlı değişiklikleri, gerçekleştikleri anda ve periyodik tam senkronizasyonlarla birlikte gönderebilirsiniz.
Silme Davranışı Dolaylı (Anlık Görüntü): Her dosya tam bir anlık görüntüdür. Birincil dosyanızdan bir satır kaldırıldığında ürün silinir. Açık: Anlık görüntü kavramı yoktur. Kullanımdan kaldırılan bir ürünü kaldırmak için productInputs.delete yöntemini çağırın.
Kaynak Temsili Tek durum: Dosyanızın satırları ham girişi temsil eder. Ham ve işlenmiş verileri ayırma: API, verileri ProductInput (ham girişiniz) ve Product (nihai işlenmiş durum) olarak ayırır.
Özellik (feed) kuralları Merchant Center kullanıcı arayüzündeki ham dosya sütunlarına uygulanır. Merchant Center kullanıcı arayüzünde desteklenir. API verileri 3. taraf ek dosyalarla birleştirilirken gereklidir. Arka ucunuzda işleniyorsa tek kaynaklı dönüşümler için isteğe bağlıdır.

Paralel kullanım ve birincil veri kaynağı sahipliği ("son güncelleme geçerli olur")

Aynı Merchant Center hesabında hem dosya feed'lerini hem de API'yi kullanabilirsiniz. Ancak belirli bir ürünü eklemek için yalnızca bir yöntem kullanmanızı önemle tavsiye ederiz.

Merchant Center, "son güncelleme geçerlidir" modeline göre çalışır. En son ürün ekleme işlemini gerçekleştiren birincil veri kaynağı (API veya dosya feed'i), ilgili ürünün verilerinin birincil sahibi olur:

  • Ürün, dosya veri kaynağına ait olduğunda: Ürünün sonraki bir dosya yükleme işlemine dahil edilmemesi, dolaylı silme işlemini tetikler ve ürün Merchant Center'dan kaldırılır.
  • Ürünün sahibi API veri kaynağı olduğunda: Dosya feed'i artık ürünün sahibi olmadığından, ürünün dosya yüklemesinden çıkarılmasının bir etkisi olmaz. Kaldırmak için accounts.productInputs.delete numarasını aramanız gerekir.
  • Yanlışlıkla yeniden sahiplik riski: Güncellenmiş bir dosya feed'i, API push işleminden sonra çalışırsa ve ürünü içeriyorsa dosya veri kaynağı sahipliği yeniden kazanır. Dosyadan daha sonra çıkarılan ürünler beklenmedik şekilde silinir.

Beklenmedik silme işlemlerini veya API güncellemelerinin kaybolmasını önlemek için aynı ürünlerde hem API hem de dosya birincil veri kaynaklarını kullanarak eşzamanlı güncellemeler yapmayın.

API ile ilgili önemli noktalar

Uygulamanıza başlamadan önce Merchant API'nin aşağıdaki önemli davranışlarını anlayın:

Esnek veri kaynakları (dil veya etiket olmadan)

Belirli bir hedef feed etiketi ve dilini önceden tanımlamanızı gerektiren dosya feed'lerinin aksine Merchant API, feedLabel veya contentLanguage belirtmeden birincil veri kaynakları oluşturmanıza olanak tanır.

  • Esnek yüklemeler: Bu özellik, herhangi bir dil veya feed etiketi kombinasyonuna sahip ürünleri tek bir veri kaynağına yüklemenize olanak tanır.
  • Basitleştirilmiş yönetim: Her hedef pazar için ayrı veri kaynakları oluşturmanız ve yönetmeniz gerekmez. Not: Veri kaynağı stratejisi seçme hakkında daha fazla bilgi için Veri kaynağı stratejisi seçme başlıklı makaleyi inceleyin.

Senkronizasyon stratejisi ve kotalar

Tüm kataloğunuzu tek bir toplu işlemde yüklediğiniz dosya feed'inin aksine, Merchant API entegrasyonunuzu hem artımlı güncellemeler hem de düzenli tam senkronizasyonlar için tasarlayın:

  • Artımlı güncellemeleri düzenli tam senkronizasyonlarla birleştirin: Arka uçta ürün özellikleri değiştikçe productInputs.insert veya productInputs.patch istekleri gönderin. Yalnızca artımlı güncellemelere güvenmek, verilerinizin zaman içinde senkronizasyonunun bozulmasına neden olabilir. Bu nedenle, kataloğunuzu doğru kaynağınızla eşleştirmek için düzenli olarak tam senkronizasyonlar da çalıştırın (bu işlem, 30 günlük ürün geçerlilik süresini de yeniler). Tam senkronizasyonu ne sıklıkta çalıştıracağınız, kataloğunuzun boyutuna ve kullanılabilir API kotanıza bağlıdır.
  • API kotalarına uymak için istekleri zamana yayın: API'yi tüm ürünleriniz için aynı anda çağırmayın. Artımlı değişiklikler gerçekleştikleri anda gönderilebilir. Ancak tam senkronizasyon isteklerini gün içine eşit şekilde dağıtarak dakika başına ve günlük yöntem çağrısı kotalarınızı aşmamaya dikkat edin. Ayrıntılar için Kotalar ve sınırlar ile Ürünlerinizde sık sık güncelleme yapma başlıklı makaleleri inceleyin.

Entegrasyonunuzu test etme

Üretim ortamına geçmeden önce entegrasyon mantığınızı güvenli bir ortamda doğrulayın.

Test hesaplarını kullanma

Üretimde değişiklik yapmadan önce, taşıma işleminin ilk adımlarını korumalı alandaki bir test hesabında uygulamanızı öneririz:

  1. Test hesabı oluşturun: Yayındaki reklamları veya ücretsiz listelemeleri etkilemeden güvenli bir şekilde deneme yapmak için izole bir test hesabı oluşturun.
  2. API veri kaynağı oluşturma: API birincil veri kaynağınızı oluşturma alıştırması yapın.
  3. Özellik kurallarını test etme: Veri dönüşümlerini ve ek feed birleştirmelerini doğrulayın.
  4. Yükleri ve ürün anahtarlarını doğrulama: SKU büyük/küçük harf kullanımını, kodlamayı ve hata işlemeyi doğrulamak için örnek ürünleri gönderin.

Ayrıntılar için 1. adım: Test hesapları oluşturun bölümüne ve Test Hesapları kılavuzuna bakın.

Ürün anahtarı uyumunu doğrulama

Programatik yük ürün anahtarınızın, dosya feed'i SKU'larınızla tam olarak eşleştiğinden emin olun. Google, ürünleri aşağıdakileri birleştirerek tanımlar:

  • offerId (Dosya feed'lerinde id olarak adlandırılır, büyük/küçük harfe duyarlıdır.)
  • contentLanguage (örneğin en)
  • feedLabel (örneğin US)

Özel karakterler ve kodlama

Ürün tanımlayıcılarınız /, % veya ~ gibi karakterler içeriyorsa API çağrılarınızda kodlanmış biçimi (dolgusuz base64url kodlama) kullanın. Daha fazla bilgi için ProductInput.name sayfasına bakın.

Eşzamanlılık kontrolü

Gerçek zamanlı entegrasyonda, ağ gecikmesi nedeniyle güncellemeler sırayla gelmeyebilir. Eski güncellemelerin daha yeni verilerin üzerine yazmasını önlemek için ProductInput kaynağındaki versionNumber alanını kullanın.

Adım adım taşıma kılavuzu

Ürünlerinizin bir kısmını veya tamamını dosya feed'lerinden Merchant API'ye taşımaya karar verirseniz gösterim veya yayınlama geçmişini kaybetmeden ürünlerinizi taşımak için bu kılavuzu uygulayın.

1. Taşıma işlemini bir test hesabında prova edin.

Üretimde değişiklik yapmadan önce accounts.createTestAccount yöntemini kullanarak korumalı alana alınmış bir test hesabı oluşturun (Test Hesapları kılavuzuna bakın). Test hesapları, tekliflerin varsayılan olarak onaylandığı, alan doğrulamasının gerekli olmadığı ve verilerin hiçbir zaman herkese açık olarak sunulmadığı izole bir ortam sağlar.

Üretim kurulumunuzu yansıtmak ve taşıma işlemini uçtan uca prova etmek için test hesabınızı kullanın:

  1. Dosya feed'i kurulumunuzu yansıtın: Test hesabında bir dosya birincil veri kaynağı (ve ek veri kaynakları) oluşturun ve üretim feed'i dosyanızın bir örneğini yükleyin.
  2. Test API veri kaynağı ve kuralları oluşturun: Bir API birincil veri kaynağı oluşturun ve gerekli özellik kurallarını veya ek feed birleştirmelerini yapılandırın.
  3. Sahiplik devralma ve anahtar eşleşmesini test etme: Örnek ürünler için productInputs.insert istekleri gönderin ve API veri kaynağının, yinelenen ürünler oluşturmadan mevcut öğelerin sahipliğini aldığını doğrulayın.
  4. Güncellemeleri ve silme işlemlerini doğrulama: Kısmi güncellemeleri productInputs.patch ile, kaldırma işlemlerini ise productInputs.delete ile test edin ve sonuçta elde edilen kaynakları products.get ile inceleyin.

2. Üretim Products API'si veri kaynakları oluşturma

Verileri göndermeden önce hesabınızda API türünde bir birincil veri kaynağı oluşturun.

API birincil veri kaynağınızı oluşturma

API push'larını kabul eden bir veri kaynağı oluşturmak için dataSources uç noktasına bir POST isteği gönderin. Daha fazla bilgi için Birincil ürün veri kaynağı oluşturma başlıklı makaleyi inceleyin.

3. Özel özellik kurallarını taşıma

Özel özellik kuralları, belirli veri kaynaklarına bağlanır ve dosya veri kaynağınızdan yeni API veri kaynağınıza otomatik olarak aktarılmaz.

Özellik kurallarınızı nasıl taşıyacağınız, kuralların amacına bağlıdır:

  • Kaynaklar arası birleştirme ve üçüncü taraf ek feed'leri: Birincil API verilerini harici ek veri kaynaklarıyla (ör. üçüncü taraf tedarikçi dosyaları, envanter e-tabloları veya promosyon feed'leri) birleştirirseniz özellik kurallarını Merchant Center kullanıcı arayüzünde yeniden oluşturmanız ve yeni API veri kaynağına eklemeniz gerekir. İstemci tarafı ön işleme, birden fazla bağımsız kaynaktaki verileri birleştiren kuralların yerini alamaz.
  • Tek kaynaklı veri dönüşümleri: Birincil katalog verilerinizde tek kaynaklı temizleme, varsayılan değerler veya dize biçimlendirme için aşağıdakilerden birini seçin:
    • Arka uç dönüşümleri (Önerilir): API'yi çağırmadan önce kendi sisteminizde dönüşümleri uygulayın. Bu sayede daha fazla programatik kontrol, daha kolay test ve daha basit hata ayıklama imkanı elde edersiniz.
    • Merchant Center özellik kuralları: Merchant Center'ın yeni API veri kaynağınız için dönüşüm kurallarını otomatik olarak yönetmeye devam etmesini istiyorsanız bu kuralları Merchant Center kullanıcı arayüzünde yeniden oluşturun.

4. API entegrasyonunu etkinleştirme

Yeni Products API birincil veri kaynağınıza ürün eklemeye, mevcut ürünleri güncellemeye ve silmeye başlamak için üretim API entegrasyonunuzu etkinleştirin:

  • Ürün ekleme ve güncelleme (sahipliği devralma): Entegrasyonunuzdan productInputs.insert ve productInputs.patch istekleri gönderin. API'yi kullanarak mevcut bir dosya feed'i ürünüyle aynı anahtara (offerId, contentLanguage, feedLabel) sahip bir ürün eklediğinizde API veri kaynağı, bu ürünün sahipliğini alır ve yayınlama geçmişini korur. Daha fazla bilgi için Ürün ekleme ve Ürün ekleme ve yönetme başlıklı makaleleri inceleyin.

  • Satışı devam etmeyen ürünleri silme: Entegrasyonunuzu, kataloğunuzdan bir ürün kaldırıldığında açıkça productInputs.delete yöntemini çağıracak şekilde yapılandırın.

  • Kademeli olarak dağıtın: Büyük kataloglar için entegrasyonunuzu her seferinde bir Merchant Center alt hesabı veya bir veri kaynağı olacak şekilde etkinleştirin.

  • Eşzamanlılığı yapılandırın: Çok sayıda istek gönderiyorsanız istemcinizi eşzamanlı istekleri işleyecek ve birden fazla bağlantıyı yönetecek şekilde yapılandırın. Eşzamanlı istekler için kodu yeniden düzenleme kılavuzuna bakın.

5. Dosya veri kaynağı güncellemelerini duraklatma

API entegrasyonunuz etkinleştirildikten sonra, dosya veri kaynağının API güncellemelerinizin üzerine yazmaması için bir sonraki planlanmış dosya çalıştırmasından önce dosya güncellemelerini durdurun:

  1. SFTP/FTP konumunuza, Google Cloud Storage'a veya Google E-Tablolar'a yeni dosya yüklemeyi durdurun.
  2. Merchant Center kullanıcı arayüzünde dosya veri kaynağınıza gidin ve planlı getirmesini duraklatın.
  3. Dosya veri kaynağına ait mevcut ürünler, API entegrasyonunuz tarafından eklenene kadar 30 güne kadar yayında kalır.

6. Taşıma işleminin tamamlanmasını bekleyin ve doğrulayın

Tüm etkin ürünler dosya veri kaynağından API veri kaynağına taşınana kadar bekleyin. Artımlı güncellemeler, ürünleri değiştikçe taşır. Normal entegrasyonunuz aracılığıyla adım adım tam katalog senkronizasyonu çalıştırmak, tüm kataloğunuzun taşınmasını hızlandırır (Senkronizasyon stratejisi ve kotalar bölümüne bakın).

Bu aşamada:

  1. Merchant Center kullanıcı arayüzünde öğe sayılarını izleyin. Dosya veri kaynağı sayısı 0 değerine düşene ve API veri kaynağı sayısı etkin kataloğunuzla eşleşene kadar bekleyin.
  2. Özelliklerin ve özel özellik kurallarının beklendiği gibi birleştirildiğini doğrulamak için products.get özelliğini kullanın.
  3. Hata oranlarını ve API performansını takip etmek için Merchant Center kullanıcı arayüzündeki API teşhis aracını izleyin.

7. Dosya veri kaynağını kullanımdan kaldırma

Geçiş tamamlandıktan ve dosya feed'i öğe sayısı 0 olduktan sonra:

  1. Güncellemelerin gerçek zamanlı olarak yansıtıldığını onaylayın.
  2. Dosya tabanlı güncellemelerin yanlışlıkla API verilerinizin üzerine yazılmasını önlemek için Merchant Center kullanıcı arayüzündeki eski dosya veri kaynağını silin.
Önceki
Migrate Local Inventory Ads settings