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ış

Directory 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 Directory 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 Directory API, bu URL'ye POST isteği olarak bir bildirim mesajı gönderir.

Şu anda Directory API, Users kaynağı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 Directory API, izlenen bir kaynak değiştiğinde uygulamanızı bilgilendirir.

İzleme istekleri oluşturma

İzlenebilir her Directory API kaynağıyla ilişkili bir watch yöntemi bulunur. Bu yöntemin URI'si aşağıdaki biçimdedir:

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. Mevcut kullanıcı veya hizmet hesabı bu kaynağın sahibi değilse ya da bu kaynağa erişme izni yoksa watch isteği başarılı olmaz.

Örnekler

Tek bir alan için User kaynağına yönelik tüm izleme istekleri genel olarak şu biçimdedir:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

İ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.
  • Bu kanal için geçerlilik süresini saniye cinsinden istemek üzere params içinde ttl.

Bildirim almak istediğiniz alan adını ve etkinlik türünü belirtmek için domain ve event parametrelerini kullanın.

Bir müşterinin kullanıcı kaynağına yönelik tüm izleme istekleri genel olarak şu biçimdedir:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

Müşterinin Google Hesabı'nın benzersiz kimliğini ve bildirim almak istediğiniz etkinlik türünü belirtmek için customer ve event parametrelerini kullanın.

event için olası değerler şunlardır:

  • add: kullanıcı tarafından oluşturulan etkinlik
  • delete: Kullanıcı, etkinliği sildi
  • makeAdmin: Kullanıcı yöneticisi durumu değişikliği etkinliği
  • undelete: Kullanıcı etkinliği silmeyi geri aldı
  • update: Kullanıcı, etkinliği güncelledi

Not: Aşağıdaki örneklerde, anlaşılırlık açısından istek gövdesi çıkarılmıştır.

mydomain.com alan adı için kullanıcı tarafından oluşturulan etkinlikleri izleyin:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

my_customer kimlikli müşteri için kullanıcı tarafından oluşturulan etkinlikleri izleyin:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

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.

    Directory API'nin bu HTTPS adresine yalnızca web sunucunuzda 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 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.

  • Dizin 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 Users kaynağına yönelik 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": "B4ibMJiIhTjAQd7Ff2K2bexk8G4",
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1384823632000
}

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

  • 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 Users kaynağına yönelik watch yöntemine bakın.

İletileri senkronize etme

Bir kaynağı izlemek için bildirim kanalı oluşturduktan sonra Directory 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, 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.

Dizin API'sinin alıcı URL'nize gönderdiği sync mesajlarının 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 kanalının, isteğiniz veya Directory API'nin dahili sınırları ya da varsayılan değerleri tarafından belirlenen bir geçerlilik 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 üzereyse 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. Directory API, bu mesajları HTTPS POST istekleri olarak, bu bildirim kanalı için address özelliği olarak belirttiğiniz URL'ye 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

Directory API'nin 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 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 veya bir etkinlik adı.
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.

Kullanıcılara yönelik bildirim mesajlarının istek gövdesinde aşağıdaki bilgiler yer alır:

Mülk Açıklama
kind Bunu bir kullanıcı kaynağı olarak tanımlar. Değer: Sabit dize "admin#directory#user".
id Kullanıcı kaynağının benzersiz tanımlayıcısı.
etag Bildirim mesajının ETag'i. Kullanıcı kaynağının ETag'inden farklıdır.
primaryEmail Kullanıcının birincil e-posta adresi.

Örnekler

User kaynak etkinlikleriyle ilgili bildirim mesajları genel olarak şu biçimdedir:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

Kullanıcının sildiği bir etkinliğe örnek:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

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 Directory API üstel geri çekilme ile yeniden dener. Diğer tüm iade durumu kodları, ileti hatası olarak kabul edilir.

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/admin/directory_v1/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. Directory API'de watch yöntemleri olan çeşitli kaynak türleri olsa da 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/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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