Push bildirimleri

Bu dokümanda, bir kaynak değiştiğinde uygulamanızı bilgilendiren push bildirimlerini nasıl kullanacağınız açıklanmaktadır.

Genel bakış

Google Calendar API, kaynaklarda yapılan değişiklikleri izlemenize olanak tanıyan push bildirimleri sağlar. Bu özelliği uygulamanızın performansını artırmak için kullanabilirsiniz. Sorgulama kaynaklarının değişip değişmediğini belirlemek için ek ağ ve işlem maliyetlerini ortadan kaldırmanızı sağlar. İzlenen bir kaynak değiştiğinde Google Calendar API, uygulamanıza bildirim gönderir.

Push bildirimlerini kullanmak için yapmanız gereken iki şey vardır:

  • Alıcı URL'nizi veya "Webhook" geri arama alıcınızı ayarlayın.

    Bu, bir kaynak değiştiğinde tetiklenen API bildirim mesajlarını işleyen bir HTTPS sunucusudur.

  • İzlemek istediğiniz her kaynak uç noktası için bir bildirim kanalı oluşturun.

    Kanal, bildirim mesajları için yönlendirme bilgilerini belirtir. Kanal kurulumunun bir parçası olarak, bildirimleri almak istediğiniz belirli bir URL belirtirsiniz. Bir kanalın kaynağı her değiştiğinde Google Calendar API, bu URL'ye POST isteği olarak bir bildirim mesajı gönderir.

Google Calendar API şu anda Acl, CalendarList, Events ve Settings kaynaklarında yapılan değişikliklerle ilgili bildirimleri desteklemektedir.

Bildirim kanalları oluşturma

Push bildirimi istemek üzere izlemek istediğiniz her kaynak için bir bildirim kanalı oluşturmanız gerekir. Bildirim kanallarınız oluşturulduktan sonra, izlenen bir kaynak değiştiğinde Google Calendar API uygulamanızı bilgilendirir.

İzleme isteği gönderme

Her bir izlenebilir Google Calendar API kaynağının, aşağıdaki biçimdeki URI'da ilişkilendirilmiş bir watch yöntemi vardır:

https://www.googleapis.com/apiName/apiVersion/resourcePath/watch

Belirli bir kaynakta yapılan değişikliklerle ilgili mesajlar için bildirim kanalı oluşturmak isterseniz kaynağın watch yöntemine POST isteği gönderin.

Her bildirim kanalı hem belirli bir kullanıcıyla hem de belirli bir kaynakla (veya kaynak grubuyla) ilişkilidir. Geçerli kullanıcı bu kaynağa sahip değilse veya bu kaynağa erişim izni yoksa watch istekleri başarılı olmaz.

Örnek

Belirli bir takvimdeki etkinlik koleksiyonunda yapılan değişiklikleri izlemeye başlayın:

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}

Zorunlu özellikler

Her watch isteğiyle birlikte şunları sağlamanız gerekir:

  • Projenizde bu yeni bildirim kanalını benzersiz şekilde tanımlayan bir id özellik dizesi. Evrensel olarak benzersiz bir tanımlayıcı (UUID) veya benzer bir benzersiz dize kullanmanızı öneririz. Maksimum uzunluk: 64 karakter.

    Ayarladığınız kimlik değeri, bu kanal için aldığınız her bildirim mesajının X-Goog-Channel-Id HTTP üst bilgisinde tekrarlanır.

  • web_hook değerine ayarlanmış bir type özellik dizesi.

  • Bu bildirim kanalının bildirimlerini dinleyip yanıt veren URL'ye ayarlanmış bir address özellik dizesi. Bu, Webhook geri çağırma URL'nizdir ve HTTPS'yi kullanmalıdır.

    Google Calendar API'nin, yalnızca web sunucunuzda geçerli bir SSL sertifikası yüklüyse bu HTTPS adresine bildirim gönderebileceğini unutmayın. Geçersiz sertifikalar şunlardır:

    • Kendinden imzalı sertifikalar.
    • Güvenilmeyen bir kaynağın imzaladığı sertifikalar.
    • İptal edilmiş sertifikalar.
    • Konusu hedef ana makine adıyla eşleşmeyen sertifikalar.

İsteğe bağlı özellikler

watch isteğinizle isteğe bağlı şu alanları da belirtebilirsiniz:

  • Kanal jetonu olarak kullanılacak rastgele bir dize değeri belirten token mülkü. Bildirim kanalı jetonlarını çeşitli amaçlarla kullanabilirsiniz. Örneğin, gelen her mesajın uygulamanızın oluşturduğu bir kanala ait olduğunu doğrulamak, bildirimin adres sahteciliğine maruz kalmadığından emin olmak veya bu kanalın amacına göre iletiyi uygulamanızdaki doğru hedefe yönlendirmek için bu jetonu kullanabilirsiniz. Maksimum uzunluk: 256 karakter.

    Jeton, uygulamanızın bu kanal için aldığı her bildirim mesajında X-Goog-Channel-Token HTTP üst bilgisine eklenir.

    Bildirim kanalı jetonları kullanıyorsanız şunları yapmanızı öneririz:

    • URL sorgu parametreleri gibi genişletilebilir bir kodlama biçimi kullanın. Örnek: forwardTo=hr&createdBy=mobile

    • OAuth jetonları gibi hassas verileri eklemeyin.

  • expiration özellik dizesi, Google Calendar API'nin bu bildirim kanalı için mesaj göndermeyi durdurmasını istediğiniz tarih ve saatin Unix zaman damgasına (ms cinsinden) ayarlanır.

    Bir kanalın geçerlilik süresi varsa bu süre, uygulamanızın bu kanal için aldığı her bildirim mesajına X-Goog-Channel-Expiration HTTP üst bilgisinin (bu kez kullanıcılar tarafından okunabilir biçimde) değeri olarak eklenir.

İstek hakkında daha ayrıntılı bilgi için API Referansı'ndaki Acl, CalendarList, Etkinlikler ve Ayarlar kaynakları için watch yöntemine bakın.

Yanıtı izle

watch isteği başarıyla bildirim kanalı oluşturursa HTTP 200 OK durum kodu döndürür.

Saat yanıtının mesaj gövdesi, aşağıdaki örnekte gösterildiği gibi yeni oluşturduğunuz bildirim kanalı hakkında bilgi sağlar.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
  "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

Talebinizin bir parçası olarak gönderdiğiniz özelliklere ek olarak, döndürülen bilgiler bu bildirim kanalında izlenen kaynağı tanımlamak için resourceId ve resourceUri özelliklerini de içerir.

İade edilen bilgileri, örneğin bildirim almayı durdurmak istemeniz gibi diğer bildirim kanalı işlemlerine iletebilirsiniz.

Yanıtla ilgili daha ayrıntılı bilgi için API Referansı'ndaki Acl, CalendarList, Etkinlikler ve Ayarlar kaynakları için watch yöntemine bakın.

Mesajı senkronize et

Bir kaynağı izlemek için yeni bir bildirim kanalı oluşturduktan sonra, Google Calendar API, bildirimlerin başladığını belirtmek için bir sync mesajı gönderir. Bu mesajların X-Goog-Resource-State HTTP üst bilgisi değeri sync şeklindedir. Ağ zamanlaması sorunları nedeniyle, sync mesajını daha watch yöntemi yanıtını almadan bile alabilirsiniz.

sync bildirimini güvenle yoksayabilseniz de dilerseniz bu bildirimi kullanabilirsiniz. Örneğin, kanalı kullanmaya devam etmek istemediğinize karar verirseniz bir çağrıda X-Goog-Channel-ID ve X-Goog-Resource-ID değerlerini kullanarak bildirim almayı durdurabilirsiniz. Sonraki etkinliklere hazırlanmak amacıyla bazı başlatma işlemleri için sync bildirimini de kullanabilirsiniz.

Google Calendar API'nin alıcı URL'nize gönderdiği sync mesajlarının biçimi aşağıda gösterilmektedir.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format; present only if channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

Senkronizasyon mesajlarının X-Goog-Message-Number HTTP üst bilgisi değeri her zaman 1'dir. Bu kanal için sonraki her bildirimde, öncekinden daha büyük bir mesaj numarası yer alır. Bununla birlikte, mesaj numaraları sıralı değildir.

Bildirim kanallarını yenileme

Bildirim kanalının bir son kullanma zamanı olabilir. Bu süre, isteğinize veya herhangi bir Google Calendar API dahili sınırlarına ya da varsayılan değerine göre belirlenen bir değerdir (daha kısıtlayıcı değer kullanılır). Kanalın geçerlilik süresi (varsa) watch yöntemi tarafından döndürülen bilgilere Unix zaman damgası (ms cinsinden) olarak eklenir. Buna ek olarak, uygulamanızın bu kanal için aldığı her bildirim mesajına son kullanma tarihi ve saati (kullanıcıların okuyabileceği biçimde) X-Goog-Channel-Expiration HTTP başlığında belirtilir.

Şu anda bildirim kanalını yenilemenin otomatik bir yolu yoktur. Bir kanalın geçerlilik bitiş tarihi yaklaştığında, watch yöntemini çağırarak yeni bir kanal oluşturmanız gerekir. Her zaman olduğu gibi, yeni kanalın id özelliği için benzersiz bir değer kullanmanız gerekir. Aynı kaynak için iki bildirim kanalının etkin olduğu zaman dilimlerinin "örtüşme" olabileceğini unutmayın.

Bildirim alma

İzlenen bir kaynak her değiştiğinde, uygulamanız değişikliği açıklayan bir bildirim mesajı alır. Google Calendar API, bu mesajları bu bildirim kanalı için "adres" olarak belirttiğiniz URL'ye HTTPS POST istekleri olarak gönderir.

Bildirim mesajı biçimini anlama

Tüm bildirim mesajları, X-Goog- ön eklerine sahip bir grup HTTP üst bilgisi içerir. Bazı bildirim türleri, mesaj gövdesi de içerebilir.

Üst bilgiler

Google Calendar API tarafından alıcı URL'nize gönderilen bildirim mesajları, aşağıdaki HTTP üst bilgilerini içerir:

Başlık Açıklama
Her zaman mevcut
X-Goog-Channel-ID Bu bildirim kanalını tanımlamak için sağladığınız UUID veya başka bir benzersiz dize.
X-Goog-Message-Number Bu bildirim kanalı için bu mesajı tanımlayan tam sayı. Değer, sync mesajları için her zaman 1'dir. Kanalda gelen her mesaj için mesaj sayısı artar ancak bu sayılar sıralı değildir.
X-Goog-Resource-ID İzlenen kaynağı tanımlayan opak bir değerdir. Bu kimlik, tüm API sürümlerinde sabittir.
X-Goog-Resource-State Bildirimi tetikleyen yeni kaynak durumu. Olası değerler: sync, exists veya not_exists.
X-Goog-Resource-URI İzlenen kaynak için API sürümüne özgü bir tanımlayıcı.
Bazen mevcut
X-Goog-Channel-Expiration Bildirim kanalının sona erme tarihi ve saati. Kullanıcıların okuyabileceği biçimde belirtilir. Yalnızca tanımlanmışsa mevcut.
X-Goog-Channel-Token Uygulamanız tarafından ayarlanan ve bildirim kaynağını doğrulamak için kullanabileceğiniz bildirim kanalı jetonu. Yalnızca tanımlanmışsa mevcuttur.

Google Takvim API'sı tarafından alıcı URL'nize gönderilen bildirim iletilerinin ileti gövdesi yoktur. Bu mesajlar, güncellenen kaynaklar hakkında belirli bilgileri içermez. Değişiklik ayrıntılarının tamamını görmek için başka bir API çağrısı yapmanız gerekir.

Örnekler

Değiştirilen etkinlik koleksiyonu için bildirim mesajını değiştirin:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

Bildirimleri yanıtlama

İşlemin başarılı olduğunu belirtmek için şu durum kodlarından herhangi birini döndürebilirsiniz: 200, 201, 202, 204 veya 102.

Hizmetiniz Google'ın API istemci kitaplığını kullanır ve 500, 502, 503 veya 504 değerini döndürürse Google Takvim API'si üstel geri yükleme ile yeniden dener. Diğer tüm iade durum kodları, mesaj hatası olarak kabul edilir.

Google Calendar API bildirim etkinliklerini anlama

Bu bölümde, Google Calendar API ile push bildirimlerini kullanırken alabileceğiniz bildirim mesajlarıyla ilgili ayrıntılar yer almaktadır.

X-Goog-Resource-State Geçerlilik kapsamı Teslimat zamanı
sync EKL'ler, Takvim listeleri, Etkinlikler, Ayarlar. Yeni bir kanal başarıyla oluşturuldu. Uygulamayla ilgili bildirim almaya başlayabilirsiniz.
exists EKL'ler, Takvim listeleri, Etkinlikler, Ayarlar. Bir kaynakta değişiklik yapıldı. Olası değişiklikler arasında yeni bir kaynağın oluşturulması veya mevcut bir kaynağın değiştirilmesi ya da silinmesi bulunur.

Bildirimler durduruluyor

Son kullanma zamanı, bildirimlerin otomatik olarak durduğu zamandır. Aşağıdaki URI'da stop yöntemini çağırarak belirli bir kanal için bildirim almayı süresi dolmadan önce durdurmayı seçebilirsiniz:

https://www.googleapis.com/calendar/v3/channels/stop

Bu yöntem, aşağıdaki örnekte gösterildiği gibi en azından kanalın id ve resourceId özelliklerini sağlamanızı gerektirir. Google Calendar API, watch yöntemlerine sahip çeşitli kaynak türlerine sahip olsa bile yalnızca bir stop yöntemi olduğunu unutmayın.

Yalnızca doğru izne sahip kullanıcılar bir kanalı durdurabilir. Özellikle:

  • Kanal normal bir kullanıcı hesabı tarafından oluşturulduysa yalnızca aynı istemcideki aynı kullanıcı (yetkilendirme jetonlarındaki OAuth 2.0 istemci kimlikleri ile tanımlanır) kanalı durdurabilir.
  • Kanal bir hizmet hesabı tarafından oluşturulmuşsa aynı istemcideki kullanıcılar kanalı durdurabilir.
POST https://www.googleapis.com/calendar/v3/channels/stop
  
Authorization: Bearer {auth_token_for_current_user}
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}