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, projenizin durumunu izlemenize olanak tanıyan push bildirimleri sunar. kaynak değişikliğidir. Bu özelliği kullanarak uygulamanızın performansını artırabilirsiniz. Ekstra ağı ortadan kaldırır ve anket kaynaklarıyla ilgili maliyetlerin değişip değişmediğini belirler. İzlenen bir kaynak değiştiğinde Directory API, bu durumu kabul edersiniz.

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 şu API bildirim mesajlarını işleyen bir HTTPS sunucusudur: bir kaynak değiştiğinde tetiklenir.

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

    Kanallar, bildirim mesajları için yönlendirme bilgilerini belirtir. Kanal oluşturma işleminin bir parçası olarak, kanalınızın bildirimleri almak istiyorsunuz. Bir kanalın kaynağı değiştiğinde Directory API, POST olarak bir bildirim mesajı gönderir söz konusu URL'ye istek gönderebilir.

Şu anda Directory API, Kullanıcılar kaynağı.

Bildirim kanalları oluşturma

Push bildirimi istemek için bildirim kanalı oluşturmanız gerekir her kaynak için ayrı ayrı seçebilirsiniz. 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

Bir bir POST isteği göndererek Kaynak için watch yöntemi.

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 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", // 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 etkinliğin alanını ve türünü belirtmek için domain ve event parametrelerini kullanın.

Bir müşterinin kullanıcı 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ı, etkinliği silme işlemini geri aldı
  • update: kullanıcı tarafından güncellenen etkinlik

Not: Aşağıdaki örneklerde daha net olması için istek gövdesi hariç tutulmuştur.

mydomain.com alanı için kullanıcılar 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ı girmeniz 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.

    Ayarladığınız kimlik değeri, X-Goog-Channel-Id Her bildirimin HTTP başlığı size bir mesaj gönderecektir.

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

Bu isteğe bağlı alanları watch isteği:

  • Kanal jetonu olarak kullanılacak rastgele bir dize değerini belirten bir token özelliği. Bildirim kanalını kullanabilirsiniz kullanıma sunuyoruz. Örneğin, e-posta adresinize gönderilen her mesajın bildirimin gönderilmediğinden emin olmak için veya iletiyi bu kanalın amacına göre yeniden gönderin. Maksimum uzunluk: 256 karakter.

    Jeton, Her bildirimde X-Goog-Channel-Token HTTP başlığı uygulamanızın bu kanal için aldığı mesaj.

    Bildirim kanalı jetonları kullanıyorsanız aşağıdakileri yapmanızı öneririz:

    • URL sorgusu gibi genişletilebilir bir kodlama biçimi kullanın parametreleridir. Ö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, değer olarak dahil edilir. X-Goog-Channel-Expiration HTTP başlığının (kullanıcıların okuyabileceği bir biçimde) biçimi) ekleyebilirsiniz. aldığı tüm bildirimler de dahildir.

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

Yanıtı izle

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 başka bir bildirim kanalına aktarabilirsiniz işlemlerinize devam edebilir, örneğin almayı durdurmak istediğinizde bildirimlerine bakın.

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

Senkronizasyon mesajı

Directory API, bir kaynağı izlemek için bildirim kanalı oluşturduktan sonra bildirimlerin başladığını belirtmek için bir sync mesajı gönderir. X-Goog-Resource-State HTTP bu iletilerin üstbilgi değeri sync. Ağa bağlı zamanlama sorunları varsa sync mesajı alabilirsiniz hem de watch yöntemi yanıtını almadan önce.

sync bildirimini yoksayabilirsiniz ancak değerlendirebilirsiniz. Ö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 şunu da kullanabilirsiniz: hazırlanmak amacıyla bazı başlatma işlemleri için sync bildirimi etkinlikleri takip edebilirsiniz.

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 gönderilen her bildirimin mesaj numarası öncekinden daha büyüktür ancak mesaj numaraları sıralı değildir.

Bildirim kanallarını yenile

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, geçerlilik bitiş tarihi ve saati eklenir (kullanıcılar tarafından okunabilir biçimde) uygulamanızın bu kanal için aldığı bildirim mesajı X-Goog-Channel-Expiration HTTP üst bilgisi.

Şu anda bildirim kanallarını otomatik olarak yenilemenin bir yolu yoktur. Bir kanalın süresi dolmak üzereyse watch yöntemini çağırarak kanalı yeni bir kanalla 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ğ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 üst bilgisi içerir. Bazı bildirim türleri şunları da içerebilir: e-posta mesajı

Üst bilgiler

Directory API tarafından e-posta adresinize gönderilen bildirim mesajları URL, aşağıdaki HTTP üstbilgilerini içerir:

Başlık Açıklama
Her zaman mevcut
X-Goog-Channel-ID Bunu tanımlamak için sağladığınız UUID veya başka bir benzersiz dize bildirim kanalı.
X-Goog-Message-Number Bu bildirim için bu mesajı tanımlayan tam sayı yardımcı olur. Değer, sync mesajları için her zaman 1 olur. Kanaldaki her mesaj için ileti numaraları artar ancak bu numaralar 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 mevcuttur
X-Goog-Channel-Expiration Bildirim kanalının son geçerlilik tarihi ve saati, biçimi de vardır. Yalnızca tanımlanmışsa mevcut olur.
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 etkinlik örneği:

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ılı olduğunu 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 Directory API'yi gerektiren 500,502, 503 veya 504 değerini döndürür eksponansiyel geri yükleme ile yeniden deneme yapar. Diğer tüm döndürülen durum kodları mesaj hatası olarak kabul edilir.

Bildirimleri durdur

expiration özelliği, bildirimlerin ne zaman otomatik olarak durdurulacağını kontrol eder. Şunları yapabilirsiniz: o kanaldan önce bildirim almayı durdurmayı seçebilirsiniz. şu adreste stop yöntemini çağırarak süresi dolar: aşağıdaki URI:

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

Bu yöntem için en azından kanalın id ve resourceId özellikleri, aşağıdaki örneğe bakın. Directory API'de birden fazla watch yöntemi olan kaynaklar için yalnızca bir stop yöntemini çağırı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, 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"
}