Push Bildirimleri

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

Genel Bakış

Directory API, kaynaklardaki değişiklikleri izlemenize olanak tanıyan push bildirimleri sağlar. Bu özelliği kullanarak uygulamanızın performansını artırabilirsiniz. Değişip değişmediklerini belirlemek için kaynak sorgulaması ile ilgili ek ağ ve hesaplama maliyetlerini ortadan kaldırmanıza olanak tanır. İzlenen bir kaynak değiştiğinde Directory API, uygulamanızı bilgilendirir.

Push bildirimleri 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 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 kurulumu kapsamında, bildirim almak istediğiniz URL'yi belirtmeniz gerekir. Bir kanalın kaynağı her değiştiğinde Directory API, söz konusu URL'ye POST istek olarak bir bildirim mesajı gönderir.

Şu anda Directory API, Users kaynağındaki değişikliklerle ilgili bildirimleri desteklemektedir.

Bildirim kanalları oluşturma

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

İzleme isteği gönderme

İzlenebilir her Directory API kaynağının, aşağıdaki biçimteki bir URI'de ilişkili bir watch yöntemi vardır:

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 isterseniz kaynağın watch yöntemine bir POST 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 isteklerinin genel biçimi:

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

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

Bir müşterinin User kaynağı için tüm izleme isteklerinin genel biçimi şudur:

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

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: user admin status change event
  • undelete: kullanıcının etkinliği geri yüklemesi
  • update: kullanıcı tarafından güncellenen etkinlik

Not: Aşağıdaki örneklerde, netlik sağlamak için istek gövdesi atlanmıştır.

mydomain.com alanı 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 müşterisi 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ğiyle birlikte şu alanları sağlamanız gerekir:

  • Projenizde 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.

    Belirlediğiniz kimlik değeri, bu kanal için aldığınız her bildirim mesajının X-Goog-Channel-Id HTTP başlığında tekrarlanır.

  • web_hook değerine ayarlanmış bir type mülk dizesi.

  • Bu bildirim kanalının bildirimlerini dinleyen ve yanıtlayan URL'ye ayarlanmış bir address mülk dizesi. Bu, webhook geri çağırma URL'nizdir ve HTTPS kullanmalıdır.

    Directory API'nin bu HTTPS adresine bildirim gönderebilmesi için web sunucunuzda geçerli bir SSL sertifikasının yüklü olması gerektiğ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 birlikte aşağıdaki isteğe bağlı alanları da belirtebilirsiniz:

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

    Jeton, uygulamanızın bu kanal için aldığı her bildirim mesajındaki X-Goog-Channel-Token HTTP başlığına eklenir.

    Bildirim kanalı jetonları kullanıyorsanız aşağıdakileri 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.

  • Directory API'nin bu bildirim kanalı için mesaj göndermeyi durdurmasını istediğiniz tarih ve saatin Unix zaman damgasına (milisaniye cinsinden) ayarlanmış bir expiration mülk dizesi.

    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 başlığının değeri olarak (kullanıcı tarafından okunabilir biçimde) dahil edilir.

İstek hakkında daha fazla bilgi için API Referansı'ndaki Users kaynağının watch yöntemine bakın.

Yanıtı izleme

watch isteği başarılı bir şekilde bildirim kanalı oluşturursa HTTP 200 OK durum kodu döndürülü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 bilgi sağlanır.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

İstenen bilgiler, isteğiniz kapsamında gönderdiğiniz özelliklere ek olarak bu bildirim kanalında izlenen kaynağı tanımlamak için resourceId ve resourceUri değerlerini de içerir.

Döndürülen bilgileri diğer bildirim kanalı işlemlerine iletebilirsiniz. Örneğin, bildirim almayı durdurmak istediğinizde bu bilgileri kullanabilirsiniz.

Yanıtla ilgili daha fazla bilgi için API Referansı'ndaki Users kaynağının watch yöntemine bakın.

Mesaj senkronizasyonu

Directory API, bir kaynağı izlemek için bildirim kanalı oluşturduktan sonra bildirimlerin başladığını belirtmek için bir sync mesajı gönderir. Bu iletilerin X-Goog-Resource-State HTTP üst bilgisi değeri sync. Ağ zamanlama sorunları nedeniyle, watch yöntem yanıtını almadan önce bile sync mesajını alabilirsiniz.

sync bildirimini yoksayabilirsiniz ancak bu bildirimi kullanabilirsiniz. Örneğin, kanalı tutmak istemediğinize karar verirseniz X-Goog-Channel-ID ve X-Goog-Resource-ID değerlerini kullanarak bildirim almayı durdurabilirsiniz. Ayrıca, daha sonraki etkinliklere hazırlanmak için bazı ilklendirme işlemleri yapmak üzere sync bildirimini de kullanabilirsiniz.

Directory API'nin 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

Senkronizasyon mesajlarının X-Goog-Message-Number HTTP başlığı değeri her zaman 1 olur. Bu kanala yönelik sonraki her bildirimin mesaj numarası öncekinden daha büyüktür ancak mesaj numaraları sıralı değildir.

Bildirim kanallarını yenileme

Bildirim kanallarının geçerlilik bitiş süresi olabilir. Bu süre, isteğinizle veya Directory API'nin dahili sınırları ya da varsayılanlarıyla belirlenir (daha kısıtlayıcı değer kullanılır). Kanalın geçerlilik bitiş tarihi varsa watch yöntemi tarafından döndürülen bilgilere Unix zaman damgası (milisaniye cinsinden) olarak eklenir. Ayrıca, uygulamanızın bu kanal için aldığı her bildirim mesajında, X-Goog-Channel-Expiration HTTP başlığında geçerlilik bitiş tarihi ve saati (kullanıcı tarafından okunabilir biçimde) yer alır.

Bildirim kanallarını otomatik olarak yenileme seçeneği şu anda mevcut değildir. Bir kanalın süresi dolmak üzereyse watch yöntemini çağırarak kanalın yerini yeni bir kanalla almanız gerekir. Her zaman olduğu gibi, yeni kanalın id özelliği için benzersiz bir değer kullanmanız gerekir. Aynı kaynağa ait iki bildirim kanalının etkin olduğu bir "çakışma" dönemi olabileceğini unutmayın.

Bildirimleri alma

İzlenen bir kaynak değiştiğinde uygulamanıza değişikliği açıklayan bir bildirim mesajı gönderilir. Directory API, bu bildirimler kanalının address mülkü olarak belirttiğiniz URL'ye HTTPS POST istekleri olarak gönderir.

Bildirim mesajı biçimini yorumlama

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

Üst bilgiler

Directory 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 olur. Kanaldaki her bir sonraki ileti için ileti sayıları artar ancak bu sayılar sıralı değildir.
X-Goog-Resource-ID İzlenen kaynağı tanımlayan opak bir değer. Bu kimlik, API sürümleri genelinde sabit kalır.
X-Goog-Resource-State Bildirimi tetikleyen yeni kaynak durumu. Olası değerler: sync veya bir etkinlik adı.
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 geçerlilik süresinin sona erdiği tarih ve saat, okunabilir biçimde ifade edilir. Yalnızca tanımlanmışsa mevcuttur.
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 Bu kaynağı 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 şekildedir:

POST https://mydomain.com/notifications // Your receiving URL.
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ı tarafından silinen bir etkinliğe örnek:

POST https://mydomain.com/notifications // Your receiving URL.
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 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, üsselik geri çekilme ile yeniden dener. Diğer tüm geri gönderme durum kodları mesaj hatası olarak kabul edilir.

Bildirimleri durdur

expiration mülkü, bildirimlerin ne zaman otomatik olarak duracağını kontrol eder. Belirli bir kanalın bildirimlerini, süresi dolmadan önce şu URI'de stop yöntemini çağırarak almayı durdurabilirsiniz:

https://www.googleapis.com/admin/directory_v1/channels/stop

Bu yöntem için, aşağıdaki örnekte gösterildiği gibi en azından kanalın id ve resourceId özelliklerini sağlamanız gerekir. Dizin API'sinde watch yöntemlerine sahip birkaç tür kaynak varsa 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 kanalın oluşturulduğu istemcide bulunan ve kanalın oluşturulduğu OAuth 2.0 istemci kimlikleriyle tanımlanan kullanıcı kanalın yayınını durdurabilir.
  • Kanal bir hizmet hesabı tarafından oluşturulduysa aynı müşterideki tüm kullanıcılar kanalı durdurabilir.

Aşağıdaki kod örneğinde, bildirimlerin nasıl durdurulacağı 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"
}