Push bildirimleri

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.

  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ı 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, Admin SDK 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.

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": "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, 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 fazla bilgi için API Referansı'ndaki Etkinlikler kaynağıyla ilgili watch yöntemine bakın.

İletiyi senkronize et

Admin SDK 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.

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ı 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 herhangi bir Admin SDK API dahili sınırları ya da varsayılanları 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 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.

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

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
        }
      ]
    }
  ]
}

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ıyorsa ve 500,502, 503 veya 504 döndürüyorsa Admin SDK API, üstel geri yükleme ile yeniden deneme gerçekleştirir. Diğer tüm iade durum kodları bir 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ılar sunulmaktadır.

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

• admin
• takvim
• sürücü
• gruplar
• login
• mobil
• saml
• jeton
• user_accounts