Bu dokümanda, müşterilerinizi bilgilendiren push bildirimlerinin nasıl kullanılacağı bir kaynak değişikliğini uygulamalısınız.
Genel Bakış
Admin SDK API, uygulamanızın performansını gösteren push bildirimleri kaynak değişikliğidir. Bu özelliği, kampanyalarınızın performansını iyileştirmek için en iyi yoludur. 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 Admin SDK API, bu durumu bir uygulamadır.
Push bildirimlerini kullanmak için iki şey yapmanız gerekir:
Alıcı URL'nizi veya "webhook"unuzu ayarlayın geri arama alıcısı.
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.
Bir kanal, bildirim için yönlendirme bilgilerini belirtiyor mesaj. Kanal oluşturma işleminin bir parçası olarak, kanalınızın bildirimleri almak istiyorsunuz. Bir kanalın kaynağı değiştiğinde Admin SDK API,
POST
olarak bir bildirim mesajı gönderir söz konusu URL'ye istek gönderebilir.
Şu anda Admin SDK API, Etkinlikler 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 ayarlandıktan sonra Admin SDK API, izlenen kaynak olduğunda uygulamanızı bilgilendirir anlamına gelir.
İzleme isteğinde bulunma
İzlenebilir her Admin SDK API kaynağının ilişkilendirilmiş bir değeri vardır
watch
yöntemi, aşağıdaki biçimdeki bir URI'da yer alır:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Bir
belirli bir kaynak için bir POST
isteği gönderin
Kaynak için watch
yöntemi.
Her bildirim kanalı hem belirli bir kullanıcıyla ilişkilendirilir hem de
ya da belirli bir kaynak kümesi olabilir. watch
isteği
başarılı kullanıcı,
veya hizmet hesabı
bu kaynağa sahip veya erişim iznine sahip.
Örnekler
Etkinlikler kaynağı için tüm izleme istekleri genel formdadır:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch 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. "payload": true, // (Optional) Whether to include the payload (message body) in notifications. "expiration": 3600 // (Optional) Your requested channel expiration time. }
Yalnızca belirli etkinlikler, kullanıcılar veya uygulamalarla ilgili bildirim almak için userKey, applicationName, eventName
ve filters
parametrelerini kullanabilirsiniz.
Not: Aşağıdaki örneklerde daha net olması için istek gövdesi hariç tutulmuştur.
Tüm yönetici etkinliklerini kontrol edin:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
Tüm doküman etkinliklerini izleyin:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
Belirli bir kullanıcının yönetici etkinliğini izleme:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
Kullanıcının şifresini değiştirmek gibi belirli bir etkinlik olup olmadığını kontrol edin:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
Belirli bir dokümanda yapılan değişiklikleri takip edin:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef
Zorunlu özellikler
Her watch
isteğiyle birlikte şu alanları girmeniz gerekir:
-
Bunu benzersiz şekilde tanımlayan bir
id
özellik dizesi yeni bir bildirim kanalı oluşturabilirsiniz. Önerilerimiz evrensel olarak benzersiz bir tanımlayıcı (UUID) veya benzer bir benzersiz dize. Maksimum uzunluk: 64 karakter.Ayarladığınız kimlik değeri,
X-Goog-Channel-Id
Her bildirimin HTTP başlığı size bir mesaj gönderecektir. -
type
özellik dizesi değere ayarlandıweb_hook
. -
Şunları dinleyen URL'ye bir
address
özellik dizesi ayarlandı ve bu bildirim kanalındaki bildirimlere yanıt verir. Bu ve HTTPS kullanmalıdır.Admin SDK API'nin Bu HTTPS adresi yalnızca yüklü bir SSL sertifikası varsa sunucu. Geçersiz sertifikalar şunlardır:
- Kendinden imzalı sertifikalar.
- Güvenilmeyen bir kaynağın imzaladığı sertifikalar.
- İptal edilmiş sertifikalar.
- Konuyla eşleşmeyen sertifikalar ana makine adı.
İsteğe bağlı özellikler
Bu isteğe bağlı alanları
watch
isteği:
-
Rastgele bir dize belirten
token
özelliği kullanılacak değer. 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ını kullanıyorsanız şunları 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.
-
expiration
özellik dizesi Unix zaman damgası Admin SDK API'nin API'yi kullanmasını istediğiniz tarih ve saati (milisaniye cinsinden) bu bildirim kanalı için mesaj göndermeyi durdur.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.
İstekle ilgili daha ayrıntılı bilgi için watch
yöntemine bakın.
API Referansı'ndaki Etkinlikler kaynağı için geçerlidir.
Yanıtı izle
watch
isteği başarıyla bildirim oluşturursa
kanalından bir HTTP 200 OK
durum kodu döndürür.
Saat yanıtının ileti gövdesi, aşağıdaki örnekte gösterildiği gibi, yeni oluşturduğunuz bir bildirim kanalını kullanın.
{ "kind": "api#channel", "id": "reportsApiId", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable. }
İsteğiniz kapsamında gönderdiğiniz özelliklere ek olarak
şunları da içerir: resourceId
ve
İzlenen kaynağı belirlemek için resourceUri
bildirim kanalı.
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 ayrıntılı bilgiyi watch
sayfasında bulabilirsiniz.
yöntemini çağırın.
İletiyi senkronize et
Bir kaynağı izlemek için bildirim kanalı oluşturduktan sonra
Admin SDK API, şunu belirtmek için bir sync
mesajı gönderir:
bildirimler başlıyor. 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, Yeşil Ofis projenizde
Bunun için X-Goog-Channel-ID
ve
Şuna yapılan çağrıda X-Goog-Resource-ID
değer:
bildirim almayı durdur. Ayrıca şunu da kullanabilirsiniz:
hazırlanmak amacıyla bazı başlatma işlemlerinin yapılması için sync
bildirim
etkinlikleri takip edebilirsiniz.
Admin SDK API'nin gönderdiği sync
mesajlarının biçimi
alıcı URL'niz 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 iletilerinde her zaman X-Goog-Message-Number
HTTP olur
başlık değeri (1
). Bu kanal için takip eden her bildirimde
daha büyük bir ileti numarası; örneğin
sayılar sıralı olmaz.
Bildirim kanallarını yenile
Bildirim kanalının, bir değere sahip geçerlilik süresi olabilir.
isteğiniz veya herhangi bir Admin SDK API dahili sınırı tarafından belirlenir
veya varsayılan değerler (daha kısıtlayıcı değer kullanılır). Kanalın geçerlilik bitiş tarihi
zamanı (varsa) Unix zaman damgası olarak eklenir.
(milisaniye cinsinden) watch
yönteminin döndürdüğü bilgilerde bulunur. 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. Zaman
bir kanalın kullanım süresi dolmak üzereyse, bunu yapmak için
watch
yöntemi. Her zaman olduğu gibi,
yeni kanalın id
özelliği. Herhangi bir riskin
bir "örtüşme" olması 2 bildirim kanalının 24 saat veya 24 saat uzunluğunda
etkin olduğundan emin olun.
Bildirimleri alma
İzlenen bir kaynak değiştiğinde, uygulamanız
bir bildirim mesajı görebilirsiniz. Admin SDK API bu verileri gönderir
olarak belirttiğiniz URL'ye HTTPS POST
istekleri biçiminde gönderilir.
Bu bildirim için address
mülk
yardımcı olur.
Bildirim mesajı biçimini yorumlama
Tüm bildirim mesajları bir dizi HTTP üstbilgisini içerir ve
X-Goog-
ön ek.
Bazı bildirim türleri şunları da içerebilir:
e-posta mesajı
Üst bilgiler
Admin SDK API tarafından alıcılara gönderilen bildirim mesajları URL, aşağıdaki HTTP üstbilgilerini içerir:
Başlık | Açıklama |
---|---|
Her zaman mevcut | |
|
Bunu tanımlamak için sağladığınız UUID veya başka bir benzersiz dize bildirim kanalı. |
|
Bu bildirim için bu mesajı tanımlayan tam sayı
yardımcı olur. Değer, sync mesaj için her zaman 1 şeklindedir. Mesaj gönder
artacaktır, ancak bu sayılar kanalda daha
sıralı değildir. |
|
İzlenen kaynağı tanımlayan opak bir değer. Bu kimlik ve API sürümlerinde kararlı hale gelir. |
|
Bildirimi tetikleyen yeni kaynak durumu.
Olası değerler:
sync veya bir etkinlik adı.
|
|
İzlenen kaynak için API sürümüne özgü bir tanımlayıcı. |
Bazen mevcuttur | |
|
Bildirim kanalının son geçerlilik tarihi ve saati, biçimi de vardır. Yalnızca tanımlanmışsa mevcuttur. |
|
Uygulamanız tarafından ayarlanan bildirim kanalı jetonu ve bildirim kaynağını doğrulamak için kullanabilirsiniz. Yalnızca şu durumlarda mevcut: tanımlanmıştır. |
Etkinlikler için bildirim mesajları, istek gövdesinde aşağıdaki bilgileri içerir:
Özellik | Açıklama |
---|---|
kind |
Bu kullanıcıyı bir Etkinlik kaynağı olarak tanımlar. Değer: "admin#reports#activity " sabit dizesi. |
id |
Etkinlik kaydının benzersiz tanımlayıcısı. |
id.time |
Etkinliğin gerçekleştiği zaman. Değer ISO 8601 tarih ve saat biçimi. Saat tam tarih artı saat, dakika ve saniye cinsinden YYYY-AA-GGTsa:dk:snTZD biçimindedir. Örneğin, 2010-04-05T17:30:04+01:00. |
id.uniqueQualifier |
Birden fazla etkinlik aynı zamana sahipse benzersiz niteleyici. |
id.applicationName |
Etkinliğin ait olduğu uygulama adı. Olası değerler şunları içerir: |
id.customerId |
Google Workspace hesabının benzersiz tanımlayıcısıdır. |
actor |
İşlemi yapan kullanıcı. |
actor.callerType |
Raporda listelenen etkinliği gerçekleştiren yazarın türü. API'nin bu sürümünde callerType , raporda listelenen işlemi gerçekleştiren USER veya OAuth 2LO varlık isteğidir . |
actor.email |
Etkinlikleri bildirilen kullanıcının birincil e-posta adresi. |
actor.profileId |
Kullanıcının benzersiz Google Workspace profili kimliği. |
ownerDomain |
Yönetici konsolunun alanı veya Dokümanlar uygulamasının doküman sahibi. Bu, raporun etkinliğinden etkilenen alandır. |
ipAddress |
İşlemi yapan kullanıcının IP adresi. Bu, kullanıcının Google Workspace'e giriş yaparken kullandığı İnternet Protokolü (IP) adresidir. Kullanıcının fiziksel konumunu yansıtabilir veya yansıtmayabilir. Örneğin, IP adresi, kullanıcının proxy sunucusunun adresi veya bir sanal özel ağ (VPN) adresi olabilir. API IPv4 ve IPv6'yı destekler. |
events[] |
Rapordaki etkinlik etkinlikleri. |
events[].type |
Etkinliğin türü. Yöneticinin değiştirdiği Google Workspace hizmeti veya özelliği, eventName özelliğini kullanarak etkinlikleri tanımlayan type özelliğinde tanımlanır. |
events[].name |
Etkinliğin adı. Bu, API tarafından bildirilen etkinliğin adıdır. Ayrıca her eventName , belirli bir Google Workspace hizmeti veya özelliğiyle ilişkilidir. Bu hizmet veya özelliklerle ilgili API, etkinlik türleri halinde düzenlenir.
Genel olarak eventName istek parametreleri için:
|
events[].parameters[] |
Çeşitli uygulamalar için parametre değer çiftleri. |
events[].parameters[].name |
Parametrenin adı. |
events[].parameters[].value |
Parametrenin dize değeri. |
events[].parameters[].intValue |
Parametrenin tam sayı değeri. |
events[].parameters[].boolValue |
Parametrenin Boole değeri. |
Örnekler
Etkinlik kaynağı etkinlikleri 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: reportsApiId 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/reports/v1/activity/userKey/applications/applicationName X-Goog-Resource-State: eventName X-Goog-Message-Number: 10 { "kind": "admin#reports#activity", "id": { "time": datetime, "uniqueQualifier": long, "applicationName": string, "customerId": string }, "actor": { "callerType": string, "email": string, "profileId": long }, "ownerDomain": string, "ipAddress": string, "events": [ { "type": string, "name": string, "parameters": [ { "name": string, "value": string, "intValue": long, "boolValue": boolean } ] } ] }
Yönetici etkinliği örneği:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 596 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json X-Goog-Resource-State: CREATE_USER X-Goog-Message-Number: 23 { "kind": "admin#reports#activity", "id": { "time": "2013-09-10T18:23:35.808Z", "uniqueQualifier": "-0987654321", "applicationName": "admin", "customerId": "ABCD012345" }, "actor": { "callerType": "USER", "email": "admin@example.com", "profileId": "0123456789987654321" }, "ownerDomain": "apps-reporting.example.com", "ipAddress": "192.0.2.0", "events": [ { "type": "USER_SETTINGS", "name": "CREATE_USER", "parameters": [ { "name": "USER_EMAIL", "value": "liz@example.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 Admin SDK API'si olan 500
,502
, 503
veya 504
değerini döndürür
eksponansiyel geri yükleme ile yeniden deneme yapar.
Diğer tüm iade durum kodları, mesaj hatası olarak değerlendirilir.
Admin SDK API bildirim etkinliklerini anlama
Bu bölümde, hangi bildirimler için gönderebileceğiniz .
Reports API push bildirimleri iki tür mesaj içerir: senkronizasyon mesajları ve etkinlik bildirimleri. Mesaj türü, X-Goog-Resource-State
HTTP üst bilgisinde belirtilir. Etkinlik bildirimleri için olası değerler activities.list
yöntemiyle aynıdır. Her uygulamanın benzersiz etkinlikleri vardır:
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/reports_v1/channels/stop
Bu yöntem için en azından kanalın
id
ve resourceId
özellikleri,
aşağıdaki örneğe bakın. Admin SDK 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şturulmuşsa, aynı istemciden gelen OAuth 2.0 istemci kimliklerine göre kimlik doğrulama jetonları) kanalı durdurabilir.
- Kanal bir hizmet hesabı tarafından oluşturulduysa aynı kanalı durdurabilir.
Aşağıdaki kod örneğinde, bildirim almayı nasıl durduracağınız gösterilmektedir:
POST https://www.googleapis.com/admin/reports_v1/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }