Listings APIListings API
Oturum aç

Webhook'lara genel bakış

Listings API'nin hesap olaylarını sunucunuza nasıl gönderdiği, mevcut olaylar ve her teslimatın geçmesi gereken beş kontrol.

Bir şeyin değişip değişmediğini öğrenmek için API'yi düzenli aralıklarla sorgulamak maliyetlidir ve değişiklik her zaman biraz gecikmeli öğrenilir. Webhook'lar bunun tersini yapar: hesabınızda bir olay gerçekleştiğinde (bir yorum geldiğinde, bir konum düzenlendiğinde, bir Google Business gönderisi yayımlandığında), Listings API saniyeler içinde sizin kontrolünüzdeki bir URL'ye JSON gövdeli bir HTTP POST isteği gönderir.

Her hesap için bir webhook URL'si vardır ve olay bazında abonelik yoktur. Hesabınızda webhook'lar etkinse ve uç noktanız doğrulanmışsa, bu sayfada listelenen her olay bu tek URL'ye iletilir. event alanına göre işlem yapın ve ihtiyacınız olmayan olayları yok sayın.

İletim süreci

Her olay aynı yolu izler. Beş koşul sırayla kontrol edilir ve bunlardan herhangi biri sağlanmazsa hiçbir HTTP isteği yapılmaz, ancak girişim yine de kaydedilir.

Alabileceğiniz olaylar

Altı grupta on sekiz olay vardır. Her biri REST API üzerinden zaten yönettiğiniz bir kaynağa karşılık gelir; böylece webhook ne zaman olduğunu, uç nokta ise ne olduğunu bildirir.

GrupOlaylarİlgili REST kaynağı
listing.submission1İşletme kayıtları
profile.*3: oluşturuldu, güncellendi, silindiKonumlar
connection.*6: bağlandı, bağlantı kesildi, yeniden kimlik doğrulama, erişilemiyor, 2 × Google doğrulamasıBağlı hesaplar
interaction.*2: yorum, yanıtYorumlar
local_post.*4: oluşturuldu, yayımlandı, reddedildi, silindiGönderiler
review_analytics.*2: günlük ve haftalık anlık görüntüAnalizler

Tüm alan tabloları ve örnek veri yükleri olay başvuru belgesinde yer alır.

Kapsam dışı

Platform, burada yayımlanmış bir REST uç noktası bulunmadığı için Listings API'nin belgelemediği veya desteklemediği başka olay grupları da üretir. Yanlışlıkla eksik bırakıldıkları düşünülmesin diye burada listelenmiştir:

  • Yorum kampanyaları: campaign.*
  • Sıralamalar: rankings.*
  • Social gönderileri ve gönderi öne çıkarmaları: social_post.*
  • Social bağlantıları: social_connection.*
  • Yapay zekâ gönderi fikirleri: idea.*, idea_series.*, idea_pipeline.*, idea_image.*
  • Google Business Profile sahipliği: gbp_ownership.*

Geliştirmeye başlamadan önce bilmeniz gereken iki nokta

Teslimat denetimleri

Teslimat, belirtilen sırayla denetlenen beş koşula bağlıdır. Başarısız olan ilk denetim teslimatı durdurur; sonraki denetimlere hiç geçilmez.

#DenetimBaşarısız olursa
1Planınız webhook kullanımını içeriyor. Hesaba tanımlanan bir kullanım hakkıdır.Hiçbir şey kaydedilmez. Olay size yönlendirilmez.
2Hesapta bir webhook URL'si yapılandırılmış.Hiçbir şey kaydedilmez.
3Uç nokta doğrulaması başarılı: yalnızca bir imzalama gizli anahtarı oluşturulduktan sonra zorunlu tutulur.endpoint_unverified olarak kaydedilir.
4URL, herkese açık bir adrese çözümleniyor (HTTPS, genel DNS üzerinden çözümlenebilen ana makine adı).blocked_url olarak kaydedilir.
5Planınızın webhook sınırını aşmıyorsunuz.rate_limited olarak kaydedilir. Olay atılır, kuyruğa alınmaz.

Planlar ve sınırlar

Webhook kullanımı her planda tanınan bir haktır: Launch, Growth ve Enterprise. Deneme süresi seçtiğiniz plan kapsamında yürütülür; bu nedenle deneme hesapları ilk günden itibaren o planın sınırları dahilinde webhook kullanabilir. Bu kullanım hakkı planınıza bağlıdır; dolayısıyla anında değil, plan değişikliğinin bir parçası olarak verilir veya kaldırılır: yükseltmeye tıkladığınız anda değil, bir sonraki plan değişikliğinde veya kayıt eşitlemesinde yürürlüğe girmesini bekleyin. Kontrol panelindeki Webhooks sayfası, mevcut kullanım hakkınızı ve sınırlarınızı gösterir.

Teslimatlar ayrıca, her ikisi de planınıza bağlı olan dakikalık ve günlük sınırlara göre sayılır.

PlanDakikalıkGünlük
Launch107,200
Growth5036,000
EnterpriseSınırsızSınırsız

Webhook sınırları, planınızın API isteği sınırlarıyla aynıdır: size gönderdiğimiz olaylar için ayrılan kota, bize gönderdiğiniz istekler için ayrılan kotaya eşittir.

Bir sınır, yalnızca planınızın sınırları teslimat sürecine eşitlendikten sonra hesabınıza uygulanmaya başlar. Bu gerçekleşene kadar denetlenecek bir sınır yoktur; dolayısıyla hiçbir teslimat sayılmaz ve hiçbir olay atılmaz. Bu nedenle yeni oluşturulmuş bir hesap, planının üst sınırı uygulanmadan önce sayılmayan teslimatlar alabilir. rate_limited görülmemesini sınırın altında olduğunuzun kanıtı olarak yorumlamayın.

Sayımın işleyişi:

  • Birbirinden bağımsız iki sabit zaman aralığı: biri dakikalık, diğeri günlük. Saatlik bir webhook zaman aralığı yoktur. (İstek hızı sınırlayıcısı, farklı zaman aralıkları kullanan ayrı bir sistemdir; bu iki sistem aynı kotayı paylaşmaz.)
  • Zaman aralıkları takvime göre hizalanır, kayan aralıklar kullanılmaz: dakika sayacı her dakika başında, günlük sayaç ise UTC'ye göre her günün başında sıfırlanır.
  • Sınır aşıldığında olay atılır. Kuyruğa alınmaz, geciktirilmez, yeniden denenmez: giden teslimat sürecinin hiçbir aşamasında yeniden deneme kuyruğu yoktur ve 429 döndürülebilecek bir çağıran da yoktur. Kayıp sessizce gerçekleşmek yerine görünür olsun diye deneme, rate_limited teslimat durumuyla kaydedilir.
  • Sınırlayıcı arızalandığında teslimata izin verilir. Sınırlayıcının kendisi yanıt veremiyorsa teslimat atılmak yerine gönderilir. Arızalı bir sayaç yüzünden hiçbir zaman olay kaybetmezsiniz.

Olayları üreten taraftaki tek yerleşik hacim denetimi, profile.updated için uygulanan debounce işlemidir: zaman aralığının başında olmak üzere konum başına 60 saniyede en fazla bir teslimat yapılır. Aynı konumda art arda yapılan düzenlemeler tek bir olayda birleştirilir ve aldığınız changed_fields yalnızca zaman aralığını başlatan düzenlemeyi açıklar. Başka hiçbir şeye debounce uygulanmaz.

Teslimat zaman aralığının başında yapıldığından, 60 saniyelik aralığın başlangıcında size ulaşır: teslimatın ulaşmasıyla tetiklenen bir geri okuma yalnızca ilk düzenlemeyi görür. Zaman aralığı kapandıktan sonra, olaydan en az 60 saniye sonra ikinci bir geri okuma planlayın ve konumları ayrıca belirli aralıklarla karşılaştırıp eşitleyin; çünkü olayın kendisi için yalnızca bir teslimat denemesi yapılır ve yeniden deneme yapılmaz. Kaçırılan bir olaydan sonra verileri eşitleme bölümüne bakın.

Kurulum

  1. Bir HTTPS uç noktası oluşturun. Adresi herkese açık olarak çözümlenebilmeli, geçerli bir sertifikası olmalı, POST kabul etmeli ve 5 saniyeden kısa sürede 2xx yanıtını döndürmelidir. Özel ve dahili adresler (loopback, RFC-1918, link-local, bulut meta verisi IP adresleri) reddedilir.
  2. Webhook URL'nizi kontrol panelinin Webhooks sayfasında kaydedin. Her hesap için tüm olayları kapsayan tek bir URL kullanılır.
  3. Gizli bir imzalama anahtarı oluşturun ve sunucunuzda saklayın. Yalnızca bir kez gösterilir. Bu noktadan itibaren iletimler imzalanır ve doğrulama zorunlu olur.
  4. Uç noktayı doğrulayın. Platform imzalı bir doğrulama isteği gönderir; uç noktanız nonce değerinin onaltılık biçimdeki HMAC değeriyle yanıt verir. İşlem başarılı olduğunda uç noktanın durumu doğrulandı olarak değişir ve iletimler başlar. Kesin arayüz sözleşmesi ve çalışan kod için imzalar ve doğrulama bölümüne bakın.
  5. Olayları işleyin. İmzayı doğrulayın, veri yükünü kuyruğa ekleyin ve 200 döndürün. Asıl işi istek işleme akışının dışında yapın. Zaman aşımı, tek deneme ilkesi ve yinelenen iletimler ile sıralamaya ilişkin beklentiler için iletim davranışı bölümüne bakın.

Sonraki adımlar