Kaynak değişiklikleriyle ilgili bildirimler

Bu dokümanda, müşterilerinizi bilgilendiren push bildirimlerinin nasıl kullanılacağı bir kaynak değişikliğini uygulamalısınız.

Genel Bakış

Google Drive API, Google Drive API'sının kullanılabilmesini sağlayan push bildirimleriyle 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, Google Drive API, 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 Google Drive API, POST olarak bir bildirim mesajı gönderir söz konusu URL'ye istek gönderebilir.

Şu anda Google Drive API, files ve changes yöntemleri.

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 Google Drive API, izlenen herhangi bir kaynak olduğunda uygulamanızı bilgilendirir anlamına gelir.

İzleme isteğinde bulunma

Her izlenebilir Google Drive API kaynağının ilişkilendirilmiş bir yolu 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

Aşağıdaki kod örneğinde, files.watch yöntemi kullanılarak tek bir files kaynağındaki değişiklikleri izlemeye başlamak için bir channels kaynağının nasıl kullanılacağı gösterilmektedir:

POST https://www.googleapis.com/drive/v3/files/fileId/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
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 files channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

Aşağıdaki kod örneğinde, changes.watch yöntemiyle tüm changes içeriklerini izlemeye başlamak için bir channels kaynağının nasıl kullanılacağı gösterilmektedir:

POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

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.

    Google Drive API'sinin 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ı (milisaniye cinsinden) Google Drive API'nin 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 files ve changes yöntemleri 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": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), 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 API Referansı'ndaki files ve changes yöntemleri için geçerlidir.

İletiyi senkronize et

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

Google Drive 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ğinize veya herhangi bir Google Drive API dahili sınırına göre 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. Google Drive API, bu verileri 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

Google Drive API'si tarafından adresinize gönderilen bildirim mesajları URL, aşağıdaki HTTP üstbilgilerini içerir:

Başlık Açıklama
Her zaman mevcut
X-Goog-Channel-ID Bunu tanımlamak için sağladığınız UUID veya başka bir benzersiz dize bildirim kanalı.
X-Goog-Message-Number 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.
X-Goog-Resource-ID İzlenen kaynağı tanımlayan opak bir değer. Bu kimlik ve API sürümlerinde kararlı hale gelir.
X-Goog-Resource-State Bildirimi tetikleyen yeni kaynak durumu. Olası değerler: sync, add, remove, update, trash, untrash veya change ,
X-Goog-Resource-URI İzlenen kaynak için API sürümüne özgü bir tanımlayıcı.
Bazen mevcuttur
X-Goog-Changed Değişikliklerle ilgili ek ayrıntılar. Olası değerler: content, parents, children veya permissions , sync mesajlarıyla sağlanmadı.
X-Goog-Channel-Expiration Bildirim kanalının son geçerlilik tarihi ve saati, biçimi de vardır. Yalnızca tanımlanmışsa mevcuttur.
X-Goog-Channel-Token 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.

files ve changes için bildirim mesajları boş.

Örnekler

İstek gövdesini içermeyen files kaynak için bildirim mesajını değiştirin:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State:  update
X-Goog-Changed: content,properties
X-Goog-Message-Number: 10

İstek gövdesini de içeren changes kaynak için bildirim mesajını değiştirin:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 118
X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes
X-Goog-Resource-State:  changed
X-Goog-Message-Number: 23

{
  "kind": "drive#changes"
}

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 Google Drive 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.

Google Drive API bildirim etkinliklerini anlama

Bu bölümde, hangi bildirimler için gönderebileceğiniz .

X-Goog-Resource-State Geçerlilik kapsamı Teslim tarihi:
sync files, changes Kanal başarıyla oluşturuldu. Bununla ilgili bildirim almaya başlayabilirsiniz.
add files Bir kaynak oluşturuldu veya paylaşıldı.
remove files Mevcut bir kaynak silindi veya paylaşımı geri alındı.
update files Bir kaynağın en az bir özelliği (meta veriler) güncellenmiştir.
trash files Bir kaynak çöp kutusuna taşındı.
untrash files Bir kaynak, çöp kutusundan kaldırıldı.
change changes Bir veya daha fazla değişiklik günlüğü öğesi eklendi.

update etkinlikleri için X-Goog-Changed HTTP üst bilgisi sağlanabilir. Bu başlıkta, gerçekleşen değişiklik türlerini açıklayan virgülle ayrılmış bir liste bulunur.

Değişiklik türü Belirtir
content Kaynak içeriği güncellendi.
properties Bir veya daha fazla kaynak özelliği güncellendi.
parents Bir veya daha fazla kaynak üst öğesi eklendi ya da kaldırıldı.
children Bir veya daha fazla alt kaynak eklendi ya da kaldırıldı.
permissions Kaynak izinleri güncellendi.

X-Goog-Changed üst bilgisi içeren örnek:

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

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/drive/v3/channels/stop

Bu yöntem için en azından kanalın id ve resourceId özellikleri, aşağıdaki örneğe bakın. Google Drive API'sinde 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/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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