Push bildirimleri

Bu belgede, bir kaynak değiştiğinde uygulamanızı bilgilendiren anlık bildirimlerin nasıl kullanılacağı açıklanmaktadır.

Genel Bakış

Google Calendar API, kaynaklardaki değişiklikleri izlemenizi sağlayan push bildirimleri sunar. Bu özelliği, uygulamanızın performansını artırmak için kullanabilirsiniz. Kaynakların değişip değişmediğini belirlemek için kaynakları yoklamayla ilişkili ek ağ ve işlem maliyetlerini ortadan kaldırmanıza olanak tanır. İzlenen bir kaynak her değiştiğinde Google Calendar API, uygulamanızı bilgilendirir.

Push bildirimlerini kullanmak için iki şey yapmanız gerekir:

  • Alıcı URL'nizi veya "webhook" geri çağırma alıcınızı ayarlayın.

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

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

    Kanal, bildirim iletileri için yönlendirme bilgilerini belirtir. Kanal kurulumu sırasında, bildirimleri almak istediğiniz URL'yi belirtmeniz gerekir. Bir kanalın kaynağı her değiştiğinde Google Takvim API'si, POST isteği olarak bir bildirim mesajı gönderir.

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

Bildirim kanalları oluşturma

Anlık bildirim isteğinde bulunmak için izlemek istediğiniz her kaynak için bir bildirim kanalı oluşturmanız gerekir. Bildirim kanallarınız ayarlandıktan sonra Google Takvim API'si, izlenen herhangi bir kaynak değiştiğinde uygulamanızı bilgilendirir.

İzleme istekleri oluşturma

İzlenebilir her Google Takvim API kaynağı, aşağıdaki biçimde bir URI'de ilişkili bir watch yöntemine sahiptir:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

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

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

Örnek

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

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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

İstek gövdesinde kanalınızın id, type olarak web_hook ve alıcı URL'nizi address olarak girin. İsteğe bağlı olarak şunları da sağlayabilirsiniz:

  • Kanal jetonunuz olarak kullanacağınız bir token.
  • İstediğiniz kanalın geçerlilik süresinin milisaniye cinsinden expiration değeri.

Zorunlu özellikler

Her watch isteğinde şu alanları sağlamanız gerekir:

  • Projenizdeki bu yeni bildirim kanalını benzersiz şekilde tanımlayan bir id mülk 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 üstbilgisinde tekrar gösterilir.

  • type özelliği dizesi, web_hook değerine ayarlanmış.

  • Bu bildirim kanalı için bildirimleri dinleyen ve yanıtlayan URL'ye ayarlanmış bir address özellik dizesi. Bu, webhook geri çağırma URL'nizdir ve HTTPS kullanmalıdır.

    Google Takvim API'sinin bu HTTPS adresine yalnızca web sunucunuza geçerli bir SSL sertifikası yüklendiyse 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

Ayrıca, watch isteğinizle birlikte aşağıdaki isteğe bağlı alanları da belirtebilirsiniz:

  • Kanal jetonu olarak kullanılacak rastgele bir dize değerini belirten token özelliği. 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 için (bildirimin sahte olmamasını sağlamak amacıyla) veya bu kanalın amacına göre mesajı uygulamanızdaki doğru hedefe yönlendirmek için jetonunu kullanabilirsiniz. Maksimum uzunluk: 256 karakter.

    Jeton, uygulamanızın bu kanal için aldığı her bildirim iletisindeki X-Goog-Channel-Token HTTP üstbilgisinde yer alır.

    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.

  • Google Takvim API'sinin bu bildirim kanalı için mesaj göndermeyi durdurmasını istediğiniz tarih ve saatin expiration özelliği, Unix zaman damgası (milisaniye cinsinden) olarak ayarlanır.

    Bir kanalın geçerlilik süresi varsa bu süre, uygulamanızın bu kanal için aldığı her bildirim mesajında X-Goog-Channel-Expiration HTTP üstbilgisinin değeri olarak (insan tarafından okunabilir biçimde) yer alır.

İstekle ilgili daha fazla bilgi için API Referansı'ndaki Acl, CalendarList, Events ve Settings kaynakları için watch yöntemine bakın.

Yanıtı izleme

watch isteği başarılı bir şekilde bildirim kanalı oluşturursa HTTP 200 OK durum kodunu döndürür.

İzleme yanıtının mesaj gövdesinde, aşağıdaki örnekte gösterildiği gibi, yeni oluşturduğunuz bildirim kanalı hakkında bilgiler yer alır.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

Yanıt metninde aşağıdaki gibi kanal ayrıntıları yer alır:

  • kind: Bunun bir API kanalı kaynağı olduğunu tanımlar.
  • id: Bu kanal için belirttiğiniz kimlik.
  • resourceId: İzlenen kaynağın kimliği.
  • resourceUri: İzlenen kaynağın sürüme özel kimliği.
  • token: İstek gövdesinde sağlanan jeton.
  • expiration: Kanalın geçerlilik bitiş zamanı (milisaniye cinsinden Unix zaman damgası).

İsteğiniz kapsamında gönderdiğiniz özelliklere ek olarak, döndürülen bilgilerde bu bildirim kanalında izlenen kaynağı tanımlamak için resourceId ve resourceUri da yer alır.

Döndürülen bilgileri, bildirim almayı durdurmak istediğinizde olduğu gibi diğer bildirim kanalı işlemlerine iletebilirsiniz.

Yanıtla ilgili daha fazla bilgi için API Referansı'ndaki watch yönteminin Acl, CalendarList, Events ve Settings kaynakları bölümüne bakın.

İletileri senkronize etme

Bir kaynağı izlemek için bildirim kanalı oluşturduktan sonra Google Calendar API, bildirimlerin başlatıldığını belirtmek için sync mesajı gönderir. Bu mesajlar için X-Goog-Resource-State HTTP başlığı değeri sync'dir. Ağ zamanlaması sorunları nedeniyle, sync mesajını watch yöntemi yanıtını almadan önce almanız mümkündür.

sync bildirimini dikkate almayabilirsiniz ancak bu bildirimi kullanmanız da mümkündür. Örneğin, kanalı tutmak istemediğinize karar verirseniz bildirim almayı durdurmak için yapılan bir çağrıda X-Goog-Channel-ID ve X-Goog-Resource-ID değerlerini kullanabilirsiniz. Ayrıca, sonraki etkinliklere hazırlanmak için bazı başlatma işlemlerini yapmak üzere sync bildirimini de kullanabilirsiniz.

Google Calendar API'nin alıcı URL'nize gönderdiği sync iletilerinin biçimi aşağıda gösterilmiştir.

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 the 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

Senkronize edilen mesajların X-Goog-Message-Number HTTP başlık değeri her zaman 1 olur. Bu kanal için sonraki her bildirim, önceki bildirimden daha büyük bir mesaj numarasına sahiptir. Ancak mesaj numaraları sıralı değildir.

Bildirim kanallarını yenileme

Bildirim kanallarının, isteğiniz veya Google Calendar API'nin dahili sınırları ya da varsayılan değerleri tarafından belirlenen bir son kullanma süresi olabilir (daha kısıtlayıcı değer kullanılır). Kanalın varsa son kullanma tarihi, watch yöntemi tarafından döndürülen bilgilerde Unix zaman damgası (milisaniye cinsinden) olarak yer alır. Ayrıca, son kullanma tarihi ve saati (insan tarafından okunabilir biçimde) uygulamanızın bu kanal için aldığı her bildirim mesajında X-Goog-Channel-Expiration HTTP üstbilgisinde yer alır.

Şu anda bildirim kanallarını otomatik olarak yenilemenin bir yolu yoktur. Bir kanalın geçerlilik süresi dolmak üzereyken watch yöntemini çağırarak bu kanalı yenisiyle değiştirmeniz gerekir. Her zaman olduğu gibi, yeni kanalın id özelliği için benzersiz bir değer kullanmanız gerekir. Aynı kaynağın iki bildirim kanalının etkin olduğu bir "çakışma" süresinin olabileceğini unutmayın.

Bildirimleri alma

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

Bildirim mesajı biçimini yorumlama

Tüm bildirim iletileri, X-Goog- öneklerine sahip bir dizi HTTP üstbilgisi içerir. Bazı bildirim türleri mesaj gövdesi de içerebilir.

Üst bilgiler

Google Takvim API'si 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 diğer benzersiz dize.
X-Goog-Message-Number Bu bildirim kanalında bu mesajı tanımlayan tam sayı. Değer, sync mesajları için her zaman 1'dır. İleti numaraları, kanaldaki her sonraki ileti için artar ancak sıralı değildir.
X-Goog-Resource-ID İzlenen kaynağı tanımlayan opak değer. Bu kimlik, API sürümleri arasında kararlıdır.
X-Goog-Resource-State Bildirimi tetikleyen yeni kaynak durumu. Olası değerler: sync, exists veya not_exists.
X-Goog-Resource-URI İzlenen kaynağın API sürümüne özgü tanımlayıcısı.
Bazen mevcut
X-Goog-Channel-Expiration Bildirim kanalının geçerlilik bitiş tarihi ve saati, okunabilir biçimde ifade edilir. Yalnızca tanımlanmışsa bulunur.
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 bulunur.

Google Takvim API'si tarafından alıcı URL'nize gönderilen bildirim iletileri ileti gövdesi içermez. Bu mesajlar, güncellenen kaynaklarla ilgili belirli bilgiler içermez. Değişikliklerin tüm ayrıntıları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ştirme:

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

Başarıyı belirtmek için aşağıdaki durum kodlarından herhangi birini döndürebilirsiniz: 200, 201, 202, 204 veya 102.

Hizmetiniz Google'ın API istemci kitaplığını kullanıyorsa ve 500,502, 503 veya 504 döndürüyorsa Google Takvim API'si üstel geri çekilme ile yeniden dener. Diğer tüm iade durumu kodları, ileti 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ı hakkında ayrıntılı bilgi verilmektedir.

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

Bildirimleri durdur

expiration özelliği, bildirimlerin ne zaman otomatik olarak durdurulacağını kontrol eder. Aşağıdaki URI'de stop yöntemini çağırarak belirli bir kanal için bildirim almayı, kanalın süresi dolmadan durdurabilirsiniz: <0xx0A> <0x0

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

Bu yöntemde, aşağıdaki örnekte gösterildiği gibi en azından kanalın id ve resourceId özelliklerini sağlamanız gerekir. Google Takvim API'sinde watch yöntemleri olan çeşitli kaynak türleri varsa yalnızca bir stop yöntemi olduğunu unutmayın.

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

  • Kanal normal bir kullanıcı hesabı tarafından oluşturulduysa yalnızca kanalı oluşturan aynı istemcideki (yetkilendirme jetonlarındaki OAuth 2.0 istemci kimlikleriyle tanımlandığı şekilde) aynı kullanıcı kanalı durdurabilir.
  • Kanal bir hizmet hesabı tarafından oluşturulduysa aynı müşteriden herhangi bir kullanıcı kanalı durdurabilir.

Aşağıdaki kod örneğinde, bildirim almayı nasıl durduracağınız gösterilmektedir:

POST https://www.googleapis.com/calendar/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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