Push bildirimleri

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

Genel bakış

Admin SDK API, 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. Değişip değişmediklerini belirlemek için yoklama kaynaklarıyla ilişkili ek ağ ve işlem maliyetlerini ortadan kaldırmanızı sağlar. İzlenen bir kaynak her değiştiğinde, Admin SDK API, uygulamanıza bildirim gönderir.

Push bildirimlerini kullanmak için yapmanız gereken iki şey vardır:

  • 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 kurulumunun bir parçası olarak, bildirimleri almak istediğiniz belirli URL'yi belirtmeniz gerekir. Bir kanalın kaynağı her değiştiğinde, Admin SDK API söz konusu URL'ye POST isteği olarak bir bildirim mesajı gönderir.

Şu anda Admin SDK API, Etkinlikler 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 oluşturulduktan sonra, izlenen bir kaynak değiştiğinde Admin SDK API uygulamanızı bilgilendirir.

Saat isteği gönderme

Her bir izlenebilir Admin SDK API kaynağının, aşağıdaki biçimdeki URI'de ilişkilendirilmiş 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 POST isteği gönderin.

Her bildirim kanalı hem belirli bir kullanıcıyla hem de belirli bir kaynakla (veya kaynak grubuyla) ilişkilidir. Geçerli kullanıcı veya hizmet hesabı bu kaynağa sahip değilse veya bu kaynağa erişim izni yoksa watch istekleri başarılı olmaz.

Örnekler

Etkinlikler kaynağı için tüm izleme istekleri genel 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", // 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.
}

userKey, applicationName, eventName ve filters parametrelerini yalnızca belirli etkinlikler, kullanıcılar veya uygulamalar için bildirim almak amacıyla kullanabilirsiniz.

Not: Aşağıdaki örneklerde, daha net ifadelerle istek gövdesi atlanmıştır.

Tüm yönetici etkinlikleri için izleme:

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

Tüm doküman etkinlikleri için 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 izleyin:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

Bir kullanıcının şifresini değiştirmek gibi belirli bir etkinliği izleyin:

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ğiyle birlikte şu alanları sağlamanız gerekir:

  • Projenizde 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ış bir type özellik dizesi.

  • Bu bildirim kanalının bildirimlerini dinleyip yanıt veren URL'ye ayarlanmış bir address özellik dizesi. Bu sizin webhook geri çağırma URL'nizdir ve HTTPS kullanmalıdır.

    Admin SDK API'nin bu HTTPS adresine, yalnızca web sunucunuzda geçerli bir SSL sertifikası yüklüyse 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ı şu alanları da belirtebilirsiniz:

  • Kanal jetonu olarak kullanılacak rastgele bir dize değeri belirten token mülkü. 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 adres sahteciliğine maruz kalmadığından emin olmak veya bu kanalın amacına göre iletiyi uygulamanızdaki doğru hedefe yönlendirmek için bu jetonu kullanabilirsiniz. Maksimum uzunluk: 256 karakter.

    Jeton, uygulamanızın bu kanal için aldığı her bildirim mesajında X-Goog-Channel-Token HTTP üst bilgisine eklenir.

    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, Admin SDK API'nin bu bildirim kanalı için mesaj göndermeyi durdurmasını istediğiniz tarih ve saatin Unix zaman damgasına (milisaniye cinsinden) ayarlanır.

    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 üst bilgisinin değeri (insanlar tarafından okunabilir biçimde) olarak eklenir.

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

Yanıtı izle

watch isteği başarıyla bildirim kanalı oluşturursa 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": "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.
}

Talebinizin bir parçası olarak gönderdiğiniz özelliklere ek olarak, döndürülen bilgiler bu bildirim kanalında izlenen kaynağı tanımlamak için resourceId ve resourceUri özelliklerini de içerir.

İade edilen bilgileri, örneğin bildirim almayı durdurmak istemeniz gibi diğer bildirim kanalı işlemlerine iletebilirsiniz.

Yanıt hakkında daha fazla bilgi için API Referansındaki Etkinlikler kaynağı için watch yöntemine bakın.

Mesajı senkronize et

Admin SDK API, bir kaynağı izlemek için 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 bildirimi de kullanabilirsiniz. Örneğin, kanalı kullanmaya devam etmek 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.

Admin SDK 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ının X-Goog-Message-Number HTTP üst bilgisi değeri her zaman 1 olur. Bu kanal için sonraki her bildirimde, öncekinden daha büyük bir mesaj numarası bulunur ancak mesaj numaraları sıralı değildir.

Bildirim kanallarını yenile

Bildirim kanalının bir son kullanma zamanı olabilir. Bu süre, isteğiniz veya herhangi bir Admin SDK API dahili sınırı ya da varsayılanı tarafından belirlenen bir değere (daha kısıtlayıcı değer kullanılır) göre belirlenir. 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, uygulamanızın bu kanal için aldığı her bildirim mesajına son kullanma tarihi ve saati (kullanıcıların okuyabileceği biçimde) X-Goog-Channel-Expiration HTTP başlığında belirtilir.

Şu anda, bildirim kanalları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ının etkin olduğu zaman dilimlerinin "örtüşme" 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. Admin SDK API bu mesajları HTTPS POST istekleri olarak, bu bildirim kanalı için address mülkü olarak belirttiğiniz URL'ye 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

Admin SDK 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ı. sync mesajları için değer her zaman 1 şeklindedir. Kanalda gösterilen her mesajın sayısı artar ancak bu sayılar sıralı değildir.
X-Goog-Resource-ID İzlenen kaynağı tanımlayan opak bir değerdir. Bu kimlik, tüm API sürümlerinde sabittir.
X-Goog-Resource-State Bildirimi tetikleyen yeni kaynak durumu. Olası değerler: sync veya 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 sona erme tarihi ve saati. Kullanıcıların okuyabileceği biçimde belirtilir. Yalnızca tanımlanmışsa mevcut.
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 mevcuttur.

Etkinlikler için bildirim mesajları, istek gövdesinde aşağıdaki bilgileri içerir:

Özellik Açıklama
kind Bu kaynağı 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şme zamanı. Bu değer, ISO 8601 tarih ve saat biçimindedir. Saat, tam tarihin yanı sıra YYYY-AA-GGTsa:dk:snTZD biçiminde saat, dakika ve 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 uygulama adı. Olası değerler şunlardır:
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 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 konsolu'nun alan adı veya Dokümanlar uygulamasının doküman sahibinin alanı. Bu, raporun etkinliğinden etkilenen alandır.
ipAddress İşlemi yapan kullanıcının IP adresi. Bu, Google Workspace'e giriş yapan kullanıcının İnternet Protokolü (IP) adresidir. Bu adres, 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ü. Bir yöneticinin değiştirdiği Google Workspace hizmeti veya özelliği, eventName özelliğini kullanarak 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 ise API'nin etkinlik türleri halinde düzenlediği belirli bir Google Workspace hizmeti veya özelliğiyle ilgilidir.
Genel olarak eventName istek parametresi için:
  • eventName sağlanmazsa rapor, tüm olası eventName örneklerini döndürür.
  • Bir eventName isteğinde bulunduğunuzda API'nin yanıtı, söz konusu eventName öğesini içeren tüm etkinlikleri döndürür. Döndürülen etkinlikler, istenene ek olarak başka eventName özelliklerine de sahip olabilir.
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ğı etkinliklerine ilişkin 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

İş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ır ve 500,502, 503 veya 504 değerini döndürürse Admin SDK API, üstel geri yükleme ile yeniden dener. Diğer tüm iade durum kodları, mesaj hatası olarak kabul edilir.

Admin SDK API bildirim etkinliklerini anlama

Bu bölümde, Admin SDK API ile push bildirimlerini kullanırken alabileceğiniz bildirim mesajlarıyla ilgili ayrıntılı bilgi verilmektedir.

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 bildirimlerinin olası değerleri activities.list yöntemiyle aynıdır. Her uygulamanın benzersiz etkinlikleri vardır:

Bildirimleri durdur

expiration özelliği, bildirimlerin ne zaman otomatik olarak duracağını kontrol eder. Aşağıdaki URI'da stop yöntemini çağırarak belirli bir kanal için bildirim almayı süresi dolmadan önce durdurmayı seçebilirsiniz:

https://www.googleapis.com/admin/reports_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. Admin SDK API'de watch yöntemleri olan birkaç kaynak türü varsa yalnızca bir stop yöntemi vardır.

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 aynı istemcideki aynı kullanıcı (yetkilendirme jetonlarındaki OAuth 2.0 istemci kimlikleri ile tanımlanır) kanalı durdurabilir.
  • Kanal bir hizmet hesabı tarafından oluşturulmuşsa 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/reports_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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