Bu dokümanda, bir kaynak değiştiğinde uygulamanızı bilgilendiren push bildirimlerini nasıl kullanacağınız açıklanmaktadır.
Genel bakış
Directory API, kaynaklardaki değişiklikleri izlemenize olanak tanıyan push bildirimleri sağlar. Uygulamanızın performansını iyileştirmek için bu özelliği kullanabilirsiniz. Değişip değişip değişmediğini belirlemek için yoklama kaynaklarıyla ilgili ek ağ ve işlem maliyetlerini ortadan kaldırmanızı sağlar. Dizin API'si, izlenen bir kaynak değiştiğinde 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 mesajları için yönlendirme bilgilerini belirtir. Kanal kurulumu sırasında, bildirimleri almak istediğiniz belirli 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, Kullanıcılar kaynağında yapılan değişikliklerle ilgili bildirimleri desteklemektedir.
Bildirim kanalları oluşturma
Push bildirimi istemek üzere izlemek istediğiniz her kaynak için bir bildirim kanalı oluşturmanız gerekir. Bildirim kanallarınız ayarlandıktan sonra Directory API, izlenen herhangi bir kaynak değiştiğinde uygulamanızı bilgilendirir.
İzleme isteğinde bulun
İzlenebilir her Directory API kaynağının, aşağıdaki biçimdeki bir URI'de ilişkili watch
yöntemi bulunur:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Belirli bir kaynakta yapılan değişiklikler hakkındaki mesajlar için bildirim kanalı oluşturmak isterseniz kaynağın watch
yöntemine POST
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ı veya hizmet hesabı bu kaynağa sahip değilse ya da bu kaynağa erişim izni yoksa watch
isteği başarılı olmaz.
Örnekler
Tek bir alan adı için User
kaynağı için 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 etkinlik 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 istekleri genel 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", // 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 etkinlikdelete
: kullanıcı tarafından silinen etkinlikmakeAdmin
: kullanıcı yöneticisi durum değişikliği etkinliğiundelete
: kullanıcı, etkinliği silmeyi geri aldıupdate
: Kullanıcı tarafından güncellenen etkinlik
Not: Aşağıdaki örneklerde, daha net anlaşılması için istek gövdesine yer verilmemiştir.
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
adlı 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ğiyle birlikte aşağıdaki alanları sağlamanız gerekir:
-
Projeniz içinde bu yeni bildirim kanalını benzersiz şekilde tanımlayan bir
id
özellik 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 üst bilgisinde tekrarlanır. -
web_hook
değerine ayarlanmıştype
özelliği dizesi. -
address
mülk dizesi, bu bildirim kanalının bildirimlerini dinleyip bunlara yanıt veren URL'ye ayarlanır. Bu sizin webhook geri çağırma URL'nizdir ve HTTPS kullanması gerekir.Directory API'nin, yalnızca web sunucunuzda geçerli bir SSL sertifikası yüklüyse bu HTTPS adresine 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
watch
isteğinizle isteğe bağlı olarak şu alanları da belirtebilirsiniz:
-
Kanal jetonu olarak kullanılacak rastgele bir dize değeri belirten
token
özelliği. Bildirim kanalı jetonlarını çeşitli amaçlar için kullanabilirsiniz. Örneğin, jetonu kullanarak gelen her iletinin uygulamanızın oluşturduğu bir kanala ait olduğunu doğrulayıp bildirimin adres sahteciliğine maruz kalmadığından emin olabilir veya iletiyi, bu kanalın amacı doğrultusunda uygulamanızdaki doğru hedefe yönlendirebilirsiniz. Maksimum uzunluk: 256 karakter.Jeton, uygulamanızın bu kanal için aldığı her bildirim mesajında
X-Goog-Channel-Token
HTTP üst bilgisine dahil edilir.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.
-
expiration
mülk dizesi, Directory API'nin bu bildirim kanalı için mesaj göndermeyi durdurmasını istediğiniz tarih ve saati içeren bir Unix zaman damgasına (milisaniye cinsinden) ayarlanır.Bir kanalın geçerlilik süresi varsa uygulamanızın bu kanal için aldığı her bildirim mesajına
X-Goog-Channel-Expiration
HTTP üst bilgisinin değeri (insanlar tarafından okunabilir biçimde) olarak eklenir.
İstek hakkında daha ayrıntılı bilgi için API Referansı'ndaki Kullanıcılar kaynağı için watch
yöntemine bakın.
Yanıtı izle
watch
isteği başarıyla bildirim kanalı oluşturursa bir HTTP 200 OK
durum kodu döndürür.
Saat yanıtının mesaj gövdesi, aşağıdaki örnekte gösterildiği gibi, yeni oluşturduğunuz bildirim kanalı hakkında bilgi sağlar.
{ "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. }
İ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
de bulunur.
Döndürülen bilgileri, bildirim almayı durdurmak istemeniz gibi diğer bildirim kanalı işlemlerine iletebilirsiniz.
Yanıtla ilgili daha ayrıntılı bilgi için API Referansı'ndaki Kullanıcılar kaynağıyla ilgili watch
yöntemine bakın.
İletiyi senkronize et
Directory API, bir kaynağı izlemek için bir bildirim kanalı oluşturduktan sonra bildirimlerin başladığını belirtmek için bir sync
mesajı gönderir. Bu mesajların X-Goog-Resource-State
HTTP üst bilgisi değeri sync
şeklindedir. Ağ zamanlaması sorunları nedeniyle, watch
yöntemi yanıtını almadan önce bile sync
mesajını alabilirsiniz.
sync
bildirimini güvenle yoksayabilirsiniz, ancak bunu da kullanabilirsiniz. Örneğin, kanalı tutmak istemediğinize karar verirseniz bir çağrıda X-Goog-Channel-ID
ve X-Goog-Resource-ID
değerlerini kullanarak bildirim almayı durdurabilirsiniz. Sonraki etkinliklere hazırlanmak amacıyla bazı başlatma işlemleri için sync
bildirimini de kullanabilirsiniz.
Directory API'nin alıcı URL'nize gönderdiği sync
mesajlarının 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
Senkronizasyon mesajları her zaman 1
X-Goog-Message-Number
HTTP üst bilgi değerine sahiptir. Bu kanal için bir sonraki bildirimde, öncekinden daha büyük bir mesaj numarası vardır ancak mesaj numaraları sıralı değildir.
Bildirim kanallarını yenile
Bildirim kanalının bir geçerlilik süresi olabilir. Bu süre, isteğiniz veya Directory API dahili sınırları ya da varsayılan değerleri tarafından belirlenen bir değerdir (daha kısıtlayıcı değer kullanılır). Kanalın geçerlilik süresi (varsa) watch
yöntemi tarafından döndürülen bilgilere Unix zaman damgası (milisaniye cinsinden) olarak eklenir. Buna ek olarak, geçerlilik bitiş tarihi ve saati, uygulamanızın bu kanal için X-Goog-Channel-Expiration
HTTP üst bilgisinde aldığı her bildirim mesajına eklenir (kullanıcıların okuyabileceği biçimde).
Şu anda bir bildirim kanalını yenilemenin otomatik bir yolu yoktur. Bir kanalın geçerlilik bitiş tarihi yaklaştığında, 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ı kaynak için iki bildirim kanalı etkin olduğunda "çakışan" bir süre olabileceğini unutmayın.
Bildirim al
İ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ı, 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 mesajları, X-Goog-
ön eklerine sahip bir grup HTTP üst bilgisi 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 göster | |
|
Bu bildirim kanalını tanımlamak için sağladığınız UUID veya başka bir benzersiz dize. |
|
Bu bildirim kanalı için bu mesajı tanımlayan tam sayı. sync mesajları için değer her zaman 1 olur. Kanalda gösterilen her mesajda mesaj sayısı artar ancak bu sayılar sıralı değildir. |
|
İzlenen kaynağı tanımlayan opak bir değerdir. Bu kimlik, API sürümlerinde sabittir. |
|
Bildirimi tetikleyen yeni kaynak durumu.
Olası değerler:
sync veya etkinlik adı.
|
|
İzlenen kaynak için API sürümüne özgü bir tanımlayıcı. |
Bazen gösterilir | |
|
Bildirim kanalının süresinin dolma tarihi ve saati (kullanıcıların okuyabileceği biçimde belirtilir). Yalnızca tanımlanmışsa mevcut. |
|
Uygulamanız tarafından ayarlanan ve bildirim kaynağını doğrulamak için kullanabileceğiniz bildirim kanalı jetonu. Yalnızca tanımlanmışsa mevcuttur. |
Kullanıcılara yönelik bildirim mesajları, istek gövdesinde aşağıdaki bilgileri içerir:
Özellik | Açıklama |
---|---|
kind |
Bunu kullanıcı kaynağı olarak tanımlar. Değer: "admin#directory#user " sabit dizesi. |
id |
Kullanıcı kaynağının benzersiz tanımlayıcısı. |
etag |
Bildirim mesajının ETag. Kullanıcı kaynağının ETag'inden farklıdır. |
primaryEmail |
Kullanıcının birincil e-posta adresi. |
Örnekler
User
kaynak etkinliği için bildirim mesajları genel biçimdedir:
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 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
İşlemin başarılı olduğunu belirtmek için şu 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 yükleme ile yeniden deneme gerçekleştirir.
Diğer tüm iade durum kodları bir mesaj hatası olarak kabul edilir.
Bildirimleri durdur
expiration
özelliği, bildirimlerin ne zaman otomatik olarak duracağını kontrol eder. Belirli bir kanal için bildirim almayı, süresi dolmadan önce durdurmayı seçebilirsiniz. Bunun için aşağıdaki URI'da stop
yöntemini çağırabilirsiniz:
https://www.googleapis.com/admin/directory_v1/channels/stop
Bu yöntem, aşağıdaki örnekte gösterildiği gibi en azından kanalın id
ve resourceId
özelliklerini sağlamanızı gerektirir. Directory API'nin watch
yöntemlerine sahip ç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 bir kanalı durdurabilir. Özellikle:
- Kanal normal bir kullanıcı hesabı tarafından oluşturulmuşsa yalnızca kanalı oluşturan aynı istemcideki kullanıcı (yetkilendirme jetonlarındaki OAuth 2.0 istemci kimlikleriyle tanımlanır) kanalı durdurabilir.
- Kanal bir hizmet hesabı tarafından oluşturulduysa aynı istemcideki 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" }