Google.com'da listelerini (veya sağlayıcılarını) göstermek için toplayıcılarla iş ortaklığı yapmaya yönelik yerel hizmet reklamları (YHR). Bu kılavuzda, toplayıcıların sağlayıcıları hakkında YHR yapılandırılmış verilerini nasıl sağlayabileceği açıklanmaktadır. Özellikle, toplayıcıların LSA ile entegrasyon için uygulaması gereken API uç noktaları kümesini belgeliyoruz.
Sözlük
Toplayıcı (veya iş ortağı): Bunlar, hizmet sağladıkları sağlayıcıları toplayan ve verileri LSA'ya sağlanabilen iş ortaklarıdır.
Üçüncü taraf sağlayıcı (veya listeleme): Bunlar, bağımsız küçük işletmelerdir (ör. Ege Sıhhi Tesisat) toptancılarla ticari ilişkisi olabilir. Toplayıcılar, bu işletmelerle ilgili bilgileri Yerel Hizmetler'e sağlar.
Genel Bakış
Toplayıcılar, feed'leri kullanarak sağlayıcıları (işletmeler) hakkında Yerel Hizmetler'e veri sağlar. Her feed, birden fazla sağlayıcı hakkındaki verilerden oluşur. Bir feed'de, tek bir sağlayıcı hakkındaki veriler bir feed öğesiyle kapsüllenir. Her feed, feed'in güncelliğini gösteren bir feed zaman damgası da belirtir. Her feed'de bir feed türü de belirtilir. Bu, aşağıda açıklandığı gibi sağlayıcı profili veya sağlayıcı yorumları hakkındaki veriler olabilir.
Feed türleri
İlk entegrasyon için her feed aşağıdaki feed türlerinden biri olabilir:
Profil feed'leri: Bu feed, sağlayıcı profilleri hakkında bilgi sağlar. Her feed öğesi, belirli bir sağlayıcı hakkındaki profil bilgilerini kapsar. Bu bilgiler arasında benzersiz işletme kimliği, işletme adı, hizmet verilen konumlar, sunulan hizmetler, çalışma saatleri vb. yer alır. Feed öğesi, bu işletmeyle ilgili yayın meta verilerini de (ör. aylık bütçe tutarı, reklam durumu vb.) içerir.
Yorum feed'leri: Bu feed, sağlayıcı yorumları hakkında bilgi sağlar. Her feed öğesi, belirli bir sağlayıcıyla ilgili ayrıntılı tüketici yorumlarının bir listesini kapsar. Her tüketici yorumu; tüketici adı, puan (1-5), yorum metni, yorum zaman damgası vb. bilgilerden oluşur.
Profil feed'i ve yorum feed'indeki belirli alanlar ve bunların semantiği hakkında daha fazla bilgi.
Feed aktarımı
Feed verileri JSON olarak serileştirilir. LSA, veri göndermek için yalnızca çekme mekanizmasını destekler. Gelecekte push mekanizmasının desteklenmesi planlanmaktadır.
Çekme mekanizması
Çekme mekanizmasında toplayıcılar, JSON nesneleri gönderen ve alan bir dizi önceden tanımlanmış REST uç noktasını (URL) destekler. Bu, bir web sunucusunda bir veya daha fazla dosya barındırmaya benzer. LSA, veri getirmek için bu URL'lere düzenli olarak HTTP GET istekleri gönderir. Önceden tanımlanmış URL'lerle ilgili ayrıntıları API uç noktalarıyla ilgili bir sonraki bölümde bulabilirsiniz.
İtme mekanizması
Push mekanizmasında LSA, toplayıcıların arayıp veri sağlayabileceği bir uç nokta sunar. Anlamsal olarak bu, çekme işlemiyle aynıdır ancak toplayıcıların belirli verileri Yerel Hizmetler'e göndermek istediği durumlarda esneklik sağlar. Protokolde açıklanan tüm semantikler, kurallar veya kısıtlamalar hem push hem de pull için aynı şekilde geçerlidir.
API uç noktaları
Toplayıcılar tarafından aşağıdaki uç noktalar desteklenmelidir: biri profil feed'i, diğeri ise yorum feed'i için.
Önerilen uç nokta yolu
Uç noktaların aşağıdaki gibi sürüm bilgilerini içermesini öneririz. v1 ile başlıyoruz.
| Uç nokta | Path |
|---|---|
| Profil feed'i | /feeds/{version}/profile |
| Yorum feed'i | /feeds/{version}/review |
Uç nokta parametresi
| Params | Açıklama |
|---|---|
maxresults |
Bu, bir sayfada kaç feed öğesi istenebileceğiyle ilgili sınırdır. |
nextpagetoken |
Sonuçların sonraki sayfasını almak için kullanılan sayfalama jetonu |
Uç nokta kimlik doğrulaması
Kimlik doğrulama için HTTP temel erişim kimlik doğrulaması kullanılır: base64 kodlu kullanıcı adı ve şifre. Aşağıda bir örnek verilmiştir.
username"Yetkilendirme" (örnek amaçlı)passwordJ9adfdsafc3RfMjpVU1yif5XMw” (örnek amaçlı)
Push için SFTP dropbox
Dropbox yolu: partnerupload.google.com:19321
UYARI: Bu SFTP bırakma kutusuna yüklenen dosyalar 24 saat sonra otomatik olarak silinir.
Uç nokta kimlik doğrulaması
Genel/özel anahtar çifti (önerilir)
- Anahtar çiftleri oluşturmak için buradaki eğiticiden yararlanın.
- LSA'ya ortak anahtarı gönderin ve kimlik doğrulama için özel anahtarı saklayın.
- LSA, kullanıcı adı oluşturmak için ortak anahtarı kullanır ve toplayıcıya geri gönderir.
Şifre kimlik doğrulaması
- LSA, kullanıcı adını ve şifreyi oluşturup toplayıcıya geri gönderir.
SFTP komutuyla ilgili hızlı referans
Giriş yapın. Oturum açmak için bu komutu kullanın. (Özel anahtar kullanmıyorsanız -i
seçeneğini eklemeyin). sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.comDosyayı kopyalayın. Dosyayı uzak sisteme kopyalayın. Dosyayı bulmak için yerel sisteminizde
lls/lcdkullanarakls/cdyapabilirsiniz. Ardından dosyayı şu yollarla kopyalayın:put <path_to_local_file>Doğrula'yı tıklayın. SFTP dizinindeki klasör ve dosyaların listesini görmek için
lskomutunu kullanın ve dosyanızın uzak sisteme kopyalandığını doğrulayın.
Feed Kategorileri
Daha önce belirtildiği gibi, her feed bir dosyaya benzer ve birkaç feed öğesinden oluşur. Her feed öğesi, belirli bir sağlayıcıyla (benzersiz işletme kimliği) ilgili verileri kapsar. Her feed'de, feed'in güncelliğini gösteren bir zaman damgası da bulunur. Feed Kategorisi, LSA'nın belirli bir feed'i nasıl yorumladığını belirtir. Aşağıda açıklandığı gibi iki feed kategorisi vardır.
Anlık görüntü feed'i, belirli bir zaman damgasında bir toplayıcı altındaki sağlayıcıların tam listesini içerir. Bu anlık görüntü feed'i işlendikten sonra aşağıdaki semantikler geçerli olur:
Feed'de bulunan tüm sağlayıcılar için sistem, LSA veritabanındaki bu sağlayıcının verilerini günceller (ör. ilk kez karşılaşıldığında yeni bir sağlayıcı oluşturur veya sağlayıcı daha önceki bir feed'de işlendiyse sağlayıcı verilerini günceller).
Şu anda LSA veritabanında bulunan ancak feed'de eksik olan herhangi bir sağlayıcı, toplayıcı altında silinir.
Güncelleme (veya artımlı) feed'i, belirli bir zaman damgasında sağlayıcıların (bir toplayıcı altında) kısmi bir listesini içerir. Artımlı feed işlendikten sonra aşağıdaki semantikler geçerli olur:
Feed'de bulunan tüm sağlayıcılar için sistem, sağlayıcı daha önceki bir anlık görüntü feed'inde oluşturulmuşsa LSA veritabanındaki bu sağlayıcıya ait verileri günceller. (ör. bir sağlayıcıyla ilk kez karşılaşılıyorsa işlem yapılmaz)
Şu anda LSA veritabanında bulunan ancak feed'de bulunmayan sağlayıcılar için bu işlem yapılmaz (yani bu sağlayıcıda herhangi bir değişiklik olmaz).
Profil ve yorum feed'i arasındaki semantik biraz farklıdır. İşleme ayrıntıları için feed'lerin semantiğine tek tek bakın.
Profil feed'leri: * Çekmeye dayalı anlık görüntü feed'leri * Göndermeye dayalı anlık görüntü feed'leri * Göndermeye dayalı güncelleme feed'leri Yorum feed'leri: * Çekmeye dayalı anlık görüntü feed'leri * Göndermeye dayalı anlık görüntü feed'leri
Aşağıdakiler için ayrı profil feed'leri gerekir:
Google Güvencesi veya Google Screened rozeti için uygun olduğu belirlenen sağlayıcılar.
Rozet için uygun olmayan sağlayıcılar.
Örnekler
Anlık görüntü feed'leri
Anlık görüntü feed'inin, sağlayıcıların tam listesini içereceğini unutmayın. Örneğin, bir toplayıcı 100 sağlayıcının LSA'ya dahil edilmesini istiyorsa anlık görüntü feed'i 100 sağlayıcının tamamı için en son durumu içermelidir.
İşleyiş şekli
Aşağıda, profil feed'lerinin anlık görüntü kategorisinin nasıl çalıştığını gösteren basit bir örnek verilmiştir.
- Anlık görüntü 1'de Pro 1 ve Pro 2 var.
- Anlık görüntü 2'de Pro 1 ve Pro 3 var.
1. anlık görüntü işlendikten sonra LSA veritabanında 1. Uzman ve 2. Uzman yer alır. Genel Görünüm 2 işlenirken LSA, Uzman 1'i güncelleyecek, Uzman 3'ü oluşturacak ve Uzman 2'yi silecektir. Yani, Anlık Görüntü 2 işlendikten sonra LSA veritabanında Pro 1 ve Pro 3 olacaktır.
Güncelleme (ek) feed'leri
Güncelleme feed'inin, bir toplayıcı altındaki sağlayıcıların kısmi bir listesini içerdiğini unutmayın. Örneğin, bir toplayıcı daha önce sağladığı 100 sağlayıcıdan yalnızca 5'ini güncellemek istiyorsa güncelleme feed'i yalnızca bu 5 sağlayıcının en son durumunu içermelidir.
İşleyiş şekli
Aşağıda, "profil feed'leri" güncelleme kategorisinin nasıl çalıştığını gösteren basit bir örnek verilmiştir.
- 1. güncelleme: Pro 1, Pro 2
- 2. güncelleme: Pro 1, Pro 3
1. güncelleme işlendikten sonra LSA veritabanında 1. Uzman ve 2. Uzman yer alır. 2. Güncelleme işlenirken LSA, Pro 1'i güncelleyecek ve Pro 3'ü oluşturacaktır. Pro 2'nin değiştirilmediğini unutmayın. Yani, 2. güncelleme işlendikten sonra LSA veritabanında Pro1, Pro2 ve Pro 3 olacaktır.
Anlık Görüntü ve Çekme'nin etkileri
Anlık görüntü feed'leri + çekme mekanizması aşağıdaki kısıtlamaları içerir:
- İş ortaklarının sağlayıcı eklemesi veya silmesi, profil bilgilerini güncellemesi, reklamları duraklatması ya da bütçeleri değiştirmesi birkaç saat sürebilir. Gecikme, çekme isteklerinin sıklığıyla doğrudan ilişkilidir.
- Acil veri güncellemeleri için tek seferlik/geçici bir çekme işlemini manuel olarak desteklememiz gerekebilir.
Artımlı ve Push desteğinin etkileri
Feed'leri güncelleme + push mekanizmasının açılması aşağıdaki iyileştirmeleri beraberinde getirir:
- İş ortakları, anlık görüntü feed'ini push veya pull yöntemiyle sunabilir. Uç noktayı (çekme için) korumak istemeyen iş ortakları, uç nokta bakım maliyetini azaltmak için bunun yerine push kullanabilir. İş ortağı, çekme işleminde anlık görüntü feed'lerini zaten destekliyor. Çekme işleminde anlık görüntü sunmaya devam edebilirsiniz.
- İş ortakları, artımlı güncellemeleri kullanarak yalnızca bir sağlayıcı alt kümesini profil değişiklikleriyle güncelleyebilir. Bu, profil verilerinin güncelliğini artırır.
- Anlık görüntü ve artımlı, push ve pull yöntemleri arasında nasıl seçim yapılacağıyla ilgili olarak önerilen entegrasyon yaklaşımı için bu bölümü inceleyin.
Önerilen entegrasyon yaklaşımı
İş ortaklarının, push veya pull yöntemiyle düzenli olarak anlık görüntü feed'leri göndermesi gerekir. Bu sayede LSA, güncellemelerin kaçırılması durumunda geri alma ve sistem kurtarma gibi acil durumları yönetebilir.
- Anlık görüntü profili feed'leri, temel veri güncelliğini garanti etmek için 2 saatte bir gönderilmelidir. Yorum feed'leri ise 6 saatte bir gönderilmelidir.
- LSA, çekme mekanizmasıyla temel verilerin güncelliğini garanti etmek için 2 saatte bir anlık görüntü profil feed'lerini ve 6 saatte bir inceleme feed'lerini çeker.
- İş ortaklarının anlık görüntü feed'leri yayınlamak için iki mekanizmadan (push veya pull) yalnızca birini kullanması yeterlidir.
İsteğe bağlı olarak, veri güncelliğini artırmak isteyen iş ortakları, push yoluyla güncelleme feed'leri gönderebilir. LSA, güncelleme feed'lerini çekmez.
- Güncelleme feed'leri, son anlık görüntüden bu yana değişen öğeleri bir sonraki anlık görüntünün alınmasını beklemeden yaymak için kullanılır.
- LSA, sağlayıcıların iki push bildirimi arasında 5 dakikadan uzun bir aralık bırakmasını önerir.
- Feed öğelerini makul bir şekilde güncelleme feed'inde paketlemeniz önerilir. LSA, 5 sağlayıcıyı güncellemek için her biri 1 feed öğesi içeren 5 güncelleme feed'i göndermek yerine 5 feed öğesi içeren 1 güncelleme feed'i gönderilmesini tercih eder.
- LSA, ek feed'leri yalnızca profil feed'leri için destekler, yorum feed'leri için desteklemez.
LSA, veri tutarlılığını garanti etmek için meta verilerdeki feedTimestampMicros alanını dikkate alır. Aynı ürünü güncelleyen daha yeni bir öğe alınmışsa eski zaman damgasına sahip feed öğesi, güncelliğini yitirmiş öğe eklenmesini önlemek için atlanır. Anlık görüntü ve güncelleme feed'lerinde feedTimestampMicros kullanarak verilerin güncelliğini doğru şekilde yansıtmak iş ortağının sorumluluğundadır.
İş ortakları, sağlayıcı başına potansiyel müşteriler ve ücretler hakkında bilgi edinmek için Raporlama API'sini kullanmalıdır.