Push bildirimleri

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 mülk dizesi. Evrensel olarak benzersiz bir tanımlayıcı (UUID) veya benzer bir benzersiz dize kullanmanızı öneririz. Maksimum uzunluk: 64 karakter.

  Belirlediğiniz kimlik değeri, bu kanal için aldığınız her bildirim mesajının X-Goog-Channel-Id HTTP başlığında tekrarlanır.

• web_hook değerine ayarlanmış bir type mülk dizesi.

• Bu bildirim kanalının bildirimlerini dinleyen ve yanıtlayan URL'ye ayarlanmış bir address mülk dizesi. Bu, webhook geri çağırma URL'nizdir ve HTTPS kullanmalıdır.

  Yönetici SDK'sı API'sinin bu HTTPS adresine bildirim gönderebilmesi için web sunucunuzda geçerli bir SSL sertifikasının yüklü olması gerektiğ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 şu isteğe bağlı alanları da belirtebilirsiniz:

• Kanal jetonu olarak kullanılacak rastgele bir dize değeri 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 (bildirimin kimliğe bürünmemesini sağlamak) veya mesajı bu kanalın amacına göre uygulamanızdaki doğru hedefe yönlendirmek için jetonu kullanabilirsiniz. Maksimum uzunluk: 256 karakter.

  Jeton, uygulamanızın bu kanal için aldığı her bildirim mesajındaki X-Goog-Channel-Token HTTP başlığına eklenir.

  Bildirim kanalı jetonları kullanıyorsanız aşağıdakileri 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.

• Admin SDK API'nin bu bildirim kanalı için mesaj göndermeyi durdurmasını istediğiniz tarih ve saatin Unix zaman damgası (milisaniye cinsinden) değerine ayarlanmış bir expiration mülk dizesi.

  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 başlığının değeri olarak (kullanıcı tarafından okunabilir biçimde) dahil edilir.

Yanıtı izle

watch isteği başarılı bir şekilde bildirim kanalı oluşturursa HTTP 200 OK durum kodu döndürülür.

İzleme 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.
}

Döndürülen bilgiler, isteğiniz kapsamında gönderdiğiniz özelliklere ek olarak bu bildirim kanalında izlenen kaynağı tanımlamak için resourceId ve resourceUri öğelerini de içerir.

Döndürülen bilgileri diğer bildirim kanalı işlemlerine iletebilirsiniz. Örneğin, bildirim almayı durdurmak istediğinizde bu bilgileri kullanabilirsiniz.

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

Senkronizasyon mesajı

Bir kaynağı izlemek için bildirim kanalı oluşturduktan sonra Yönetici SDK'sı API'si, bildirimlerin başladığını belirtmek için bir sync mesajı gönderir. Bu iletilerin X-Goog-Resource-State HTTP üst bilgisi değeri sync. Ağ zamanlama sorunları nedeniyle, watch yöntem yanıtını almadan önce bile sync mesajını alabilirsiniz.

sync bildirimini yoksayabilirsiniz ancak bu bildirimi kullanabilirsiniz. Örneğin, kanalı tutmak istemediğinize karar verirseniz 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ö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 mesajlarının X-Goog-Message-Number HTTP başlığı değeri her zaman 1 olur. Bu kanala yönelik sonraki her bildirimin mesaj numarası öncekinden daha büyüktür ancak mesaj numaraları sıralı değildir.

Bildirim kanallarını yenileme

Bildirim kanalının son kullanma zamanı olabilir. Bu süre, isteğinizle veya Admin SDK API'deki dahili sınırlarla ya da varsayılanlarla belirlenir (daha kısıtlayıcı değer kullanılır). Kanalın geçerlilik bitiş tarihi (varsa) watch yöntemi tarafından döndürülen bilgilere Unix zaman damgası (milisaniye cinsinden) olarak eklenir. Ayrıca, uygulamanızın bu kanal için aldığı her bildirim mesajına X-Goog-Channel-Expiration HTTP başlığında geçerlilik bitiş tarihi ve saati eklenir (kullanıcılar tarafından okunabilir biçimde).

Şu anda bildirim kanallarını otomatik olarak yenileme seçeneği yoktur. Kullanım süresi dolmak üzere olan bir kanalı, watch yöntemini çağırarak 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 durumlarda, bir "örtüşme" süresinin olabileceğini unutmayın.

Bildirim mesajı biçimini yorumlama

Tüm bildirim mesajları, X-Goog- ön eklerine sahip bir dizi 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

Başarıyı belirtmek için aşağıdaki durum kodlarından 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 üsselik geri çekilme ile yeniden dener. Diğer tüm iade durum kodları, mesaj hatası olarak değerlendirilir.

Admin SDK API bildirim etkinliklerini anlama

Bu bölümde, Yönetici SDK'sı API'si ile push bildirimleri kullanırken alabileceğiniz bildirim mesajları hakkında 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 bildirimleri için olası değerler, activities.list yöntemiyle aynıdır. Her uygulamanın benzersiz etkinlikleri vardır:

• admin
• calendar
• drive
• groups
• login
• mobil
• saml
• token
• user_accounts