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

Yönetici SDK'sı API'si, kaynaklardaki değişiklikleri izlemenize olanak tanıyan push bildirimleri sağlar. 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 Yönetici SDK'si API'si 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 Admin SDK API, POST isteği olarak bu URL'ye bir bildirim mesajı gönderir.

Yönetici SDK'sı API'si şu anda Etkinlikler kaynağında yapılan 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 Yönetici SDK'sı API'si, izlenen herhangi bir kaynak değiştiğinde uygulamanızı bilgilendirir.

İzleme istekleri oluşturma

İzlenebilir her Yönetici SDK'sı API kaynağı, aşağıdaki biçimde bir URI'de bulunan ilişkili bir watch yöntemine sahiptir:

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

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

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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "payload": true,
  "expiration": 3600
}

İstek gövdesi aşağıdaki özelliklere sahiptir:

  • id: Bu kanalı tanımlayan bir UUID veya benzeri benzersiz dize.
  • type: Yayınlama mekanizmasının türü. Bu alanın değeri web_hook olmalıdır.
  • address: Bildirimlerin gönderildiği URL.
  • token: Bildirimin güvenilir bir kaynaktan geldiğini doğrulamak amacıyla her bildirimle birlikte hedef adrese gönderilen rastgele bir dize.
  • payload: Yükün bildirime dahil edilip edilmeyeceğini belirten bir Boole işareti.
  • expiration: Bildirim kanalının geçerlilik süresi (saniye).

Yalnızca belirli etkinlikler, kullanıcılar veya uygulamalar için bildirim almak üzere userKey, applicationName, eventName ve filters parametrelerini kullanabilirsiniz.

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

Tüm yönetici etkinliklerini izleyin:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

Tüm Dokümanlar etkinliklerini izleme:

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ı şifresini değiştirme gibi belirli bir etkinliği izleme:

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 izleme:

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ğ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.

    Admin SDK API'nin bu HTTPS adresine yalnızca web sunucunuza geçerli bir SSL sertifikası yüklendiyse 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.

  • Bu bildirim kanalı için Admin SDK API'nin mesaj göndermeyi durdurmasını istediğiniz tarih ve saatin expiration mülk dizesi, 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 Etkinlikler 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": "reportsApiId",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 3600
}

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

İletileri senkronize etme

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

Yönetici SDK'sı 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 herhangi bir Admin SDK API'sinin dahili sınırları ya da varsayılanları tarafından belirlenen bir değerle 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. Yönetici SDK'sı API'si 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 iletileri, X-Goog- öneklerine sahip bir dizi HTTP üstbilgisi içerir. Bazı bildirim türleri mesaj gövdesi de içerebilir.

Üst bilgiler

Admin SDK API tarafından alıcı URL'nize gönderilen bildirim mesajları aşağıdaki HTTP üstbilgilerini 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.

Etkinliklerle ilgili bildirim mesajlarının istek gövdesinde aşağıdaki bilgiler yer alır:

Mülk Açıklama
kind Bunu bir Etkinlik kaynağı olarak tanımlar. Değer: Sabit dize "admin#reports#activity".
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çimindedir. Saat, YYYY-AA-GGTss:dd:ssTZD biçiminde tam tarih ve saat, dakika, saniyedir. Ö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 uygulamanın adı. Olası değerler şunlardır:
id.customerId Google Workspace hesabının benzersiz tanımlayıcısı.
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 profil kimliği.
ownerDomain Yönetici Konsolu'nun veya Dokümanlar uygulamasının doküman sahibinin alanı. Bu, rapordaki etkinlikten etkilenen alan adıdır.
ipAddress İşlemi yapan kullanıcının IP adresi. Bu, Google Workspace'e giriş yaparken kullanıcının İnternet Protokolü (IP) adresidir. Kullanıcının fiziksel konumunu yansıtıp 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 Etkinlik türü. Bir yöneticinin değiştirdiği Google Workspace hizmeti veya özelliği, eventName özelliği kullanılarak bir etkinliği tanımlayan type özelliğinde tanımlanır.
events[].name Etkinliğin adı. Bu, API tarafından bildirilen etkinliğin adıdır. Her eventName, API'nin etkinlik türleri halinde düzenlediği belirli bir Google Workspace hizmeti veya özelliğiyle ilgilidir.
Genel olarak eventName istek parametreleri için:
  • eventName verilmezse raporda eventName ile ilgili olası tüm örnekler döndürülür.
  • Bir eventName istediğinizde API'nin yanıtı, bu eventName içeren tüm etkinlikleri döndürür. Döndürülen etkinliklerde, istenen özelliğe ek olarak başka eventName özellikleri de olabilir.
events[].parameters[] Çeşitli uygulamalar için parametre değeri ç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ğı 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: 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 etkinliği örneği:

POST https://mydomain.com/notifications
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ı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 Yönetici SDK'sı API'si üstel geri çekilme ile yeniden dener. Diğer tüm iade durumu kodları, ileti hatası olarak kabul edilir.

Yönetici SDK'sı API bildirim etkinliklerini anlama

Bu bölümde, Yönetici SDK'sı API'si ile push bildirimlerini kullanırken alabileceğiniz bildirim mesajları hakkında ayrıntılı bilgi verilmektedir.

Reports API anlık bildirimleri iki tür mesaj içerir: senkronizasyon mesajları ve etkinlik bildirimleri. İleti türü, X-Goog-Resource-State HTTP üstbilgisinde 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. 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/reports_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. Admin SDK API'de watch yöntemlerine sahip ç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 kanalı yalnızca aynı istemciden (yetkilendirme jetonlarındaki OAuth 2.0 istemci kimlikleriyle tanımlandığı şekilde) aynı kullanıcı 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/reports_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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