Push bildirimi alın

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

Genel Bakış

Google Takvim API'si, kaynaklardaki değişiklikleri izlemenizi sağlayan push bildirimleri sunar. Bu özelliği, uygulamanızın performansını artırmak için kullanabilirsiniz. Bu özellik, 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ızı sağlar. İzlenen bir kaynak her değiştiğinde Google Takvim API, uygulamanıza bildirim gönderir.

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 mesajları için yönlendirme bilgilerini belirtir. Kanal kurulumu kapsamı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 Takvim API'si ş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öntemine 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şme 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.
  • İstenen kanal geçerlilik bitiş zamanınız için milisaniye cinsinden expiration süresi.

Zorunlu özellikler

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

  • Projenizdeki bu yeni bildirim kanalını benzersiz şekilde tanımlayan bir id özellik dizesi. Evrensel olarak benzersiz 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 bunlara yanıt veren URL'ye ayarlanmış bir address mülk 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üklüyse 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 için) 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 ileti 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 watch yöntemine bakın. Bu yöntem, ACL, CalendarList, Events ve Settings kaynakları için geçerlidir.

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 e-posta 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: Bunu bir API kanalı kaynağı olarak tanımlar.
  • id: Bu kanal için belirttiğiniz kimlik.
  • resourceId: İzlenen kaynağın kimliği.
  • resourceUri: İzlenen kaynağın sürüme özgü 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öntemine bakın. Bu yöntem, ACL, CalendarList, Events ve Settings kaynakları için geçerlidir.

İletileri senkronize etme

Bir kaynağı izlemek için bildirim kanalı oluşturduktan sonra Google Takvim API, bildirimlerin başladığı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, watch yöntemi yanıtını almadan önce sync mesajını alabilirsiniz.

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, daha sonraki etkinliklere hazırlanmak için bazı başlatma işlemlerini yapmak üzere sync bildirimini de kullanabilirsiniz.

Google Takvim API'nin alıcı URL'nize gönderdiği sync iletilerinin 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 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 kanalla ilgili sonraki her bildirimde, önceki bildirimden daha büyük bir mesaj numarası bulunur. Ancak mesaj numaraları sıralı olmaz.

Bildirim kanallarını yenileme

Bildirim kanallarının, isteğiniz veya Google Takvim API'sinin 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 geçerlilik bitiş zamanı, watch yöntemi tarafından döndürülen bilgilerde Unix zaman damgası (milisaniye cinsinden) olarak yer alır. Ayrıca, bu kanal için uygulamanızın aldığı her bildirim mesajında X-Goog-Channel-Expiration HTTP üstbilgisinde geçerlilik bitiş tarihi ve saati (insan tarafından okunabilir biçimde) 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 e-posta mesajı da içerebilir.

Üst bilgiler

Google Takvim API'sinin alıcı URL'nize gönderdiği 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 iletileri 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.

Takvim API'sinin alıcı URL'nize gönderdiği 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.

Örnek

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

POST https://mydomain.com/notifications
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 eksponansiyel geri yükleme ile yeniden dener. Diğer tüm iade durumu kodları, ileti hatası olarak kabul edilir.

Google Takvim API bildirim etkinliklerini anlama

Bu bölümde, Google Takvim 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. Artık bildirim alabilirsiniz.
exists EKL'ler, Takvim listeleri, Etkinlikler, Ayarlar. Bir kaynak değişti. 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ı durdurmayı seçebilirsiniz:

https://www.googleapis.com/workspace/calendar/api/v3/reference/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 kanalı yalnızca aynı istemciden (yetkilendirme jetonlarındaki OAuth 2.0 istemci kimlikleriyle tanımlandığı şekilde) aynı kullanıcı 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/workspace/calendar/api/v3/reference/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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