Kaynak değişiklikleriyle ilgili bildirimler

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

Genel Bakış

Google Drive API, kaynaklardaki değişiklikleri izleyebilmenizi sağlayan push bildirimleri sağlar. Bu özelliği kullanarak uygulamanızın performansını artırabilirsiniz. Değişip değişmediklerini belirlemek için kaynak sorgulaması ile ilgili ek ağ ve hesaplama maliyetlerini ortadan kaldırmanıza olanak tanır. İzlenen bir kaynak değiştiğinde Google Drive API, uygulamanızı bilgilendirir.

Push bildirimleri 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 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 kurulumu kapsamında, bildirim almak istediğiniz URL'yi belirtmeniz gerekir. Bir kanalın kaynağı değiştiğinde Google Drive API, ilgili URL'ye POST isteğinde bulunarak bir bildirim mesajı gönderir.

Google Drive API şu anda files ve changes yöntemlerinde yapılan değişikliklerle ilgili bildirimleri desteklemektedir.

Bildirim kanalları oluşturma

Push bildirimleri istemek için izlemek istediğiniz her kaynak için bir bildirim kanalı oluşturmanız gerekir. Bildirim kanallarınız oluşturulduktan sonra Google Drive API, izlenen bir kaynak değiştiğinde uygulamanızı bilgilendirir.

İzleme isteği gönderme

İzlenebilir her Google Drive API kaynağının, aşağıdaki biçimteki bir URI'de ilişkili 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 bir POST 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

Aşağıdaki kod örneğinde, files.watch yöntemini kullanarak tek bir files kaynağındaki değişiklikleri izlemeye başlamak için 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öntemini kullanarak tüm changes öğelerini 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ı 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.

    Google Drive API'nin 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 birlikte aşağıdaki isteğe bağlı alanları da belirtebilirsiniz:

  • Kanal jetonu olarak kullanılacak rastgele bir dize değerini belirten bir 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 için) 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.

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

İstek hakkında daha fazla bilgi için API Referansı'ndaki files ve changes yöntemleri için watch yöntemine bakın.

Yanıtı izleme

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övdesinde, aşağıdaki örnekte gösterildiği gibi, yeni oluşturduğunuz bildirim kanalı hakkında bilgi sağlanır.

{
  "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.
}

İstenen bilgiler, isteğiniz kapsamında gönderdiğiniz özelliklere ek olarak bu bildirim kanalında izlenen kaynağı tanımlamak için resourceId ve resourceUri değerlerini 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 files ve changes yöntemleri için watch yöntemine bakın.

Senkronizasyon mesajı

Google Drive API, bir kaynağı izlemek için bildirim kanalı oluşturduktan sonra 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. Ayrıca, daha sonraki etkinliklere hazırlanmak için bazı ilklendirme işlemleri yapmak üzere sync bildirimini de kullanabilirsiniz.

Google Drive 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 gönderilen her bildirimin mesaj numarası öncekinden daha büyüktür ancak mesaj numaraları sıralı değildir.

Bildirim kanallarını yenileme

Bildirim kanallarının son kullanma zamanı olabilir. Bu süre, isteğinizle veya Google Drive API'nin dahili sınırları ya da varsayılanlarıyla 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ında, X-Goog-Channel-Expiration HTTP başlığında süre sonu tarihi ve saati (kullanıcı tarafından okunabilir biçimde) yer alır.

Şu anda bildirim kanallarını otomatik olarak yenileme seçeneği yoktur. Bir kanalın süresi dolmak üzereyse 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ı kaynağa ait iki bildirim kanalının etkin olduğu bir "çakışma" dönemi olabileceğini unutmayın.

Bildirimleri alma

İzlenen bir kaynak değiştiğinde uygulamanıza değişikliği açıklayan bir bildirim mesajı gönderilir. Google Drive API, bu bildirimler kanalının address mülkü olarak belirttiğiniz URL'ye HTTPS POST istekleri olarak gönderir.

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.

Üst bilgiler

Google Drive 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ı. Değer, sync mesajları için her zaman 1 olur. Kanaldaki her mesaj için ileti numaraları artar ancak bu numaralar sıralı değildir.
X-Goog-Resource-ID İzlenen kaynağı tanımlayan opak bir değer. Bu kimlik, API sürümleri genelinde sabit kalır.
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 mevcut
X-Goog-Changed Değişikliklerle ilgili ek ayrıntılar. Olası değerler: content, parents, children veya permissions . sync iletileriyle sağlanmaz.
X-Goog-Channel-Expiration Bildirim kanalının geçerlilik süresinin sona erdiği tarih ve saat, 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.

files ve changes ile ilgili bildirim mesajları boş.

Örnekler

files kaynakları için istek gövdesi içermeyen değişiklik bildirimi mesajı:

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

changes kaynakları için istek gövdesi içeren değişiklik bildirim mesajı:

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ı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 Google Drive API, üsselik erteleme ile yeniden dener. Diğer tüm döndürülen durum kodları mesaj hatası olarak kabul edilir.

Google Drive API bildirim etkinliklerini anlama

Bu bölümde, Google Drive API ile push bildirimleri kullanırken alabileceğiniz bildirim mesajları hakkında ayrıntılı bilgi verilmektedir.

X-Goog-Resource-State Geçerli olduğu platformlar Teslim edildiği zaman
sync files, changes Kanal başarıyla oluşturuldu. Bu konuda bildirim almaya başlayabilirsiniz.
add files Bir kaynak oluşturuldu veya paylaşıldı.
remove files Mevcut bir kaynak silinmiş veya paylaşımı kaldırılmış olabilir.
update files Bir kaynağın bir veya daha fazla özelliği (meta veri) güncellendi.
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ık, gerçekleşen değişiklik türlerini açıklayan, virgülle ayrılmış bir liste içerir.

Değişiklik türü Indicates
content Kaynak içeriği güncellendi.
properties Bir veya daha fazla kaynak özelliği güncellendi.
parents Bir veya daha fazla kaynak ebeveyni eklenmiş ya da kaldırılmıştır.
children Bir veya daha fazla alt kaynak eklenmiş ya da kaldırılmıştır.
permissions Kaynak izinleri güncellendi.

X-Goog-Changed başlığı içeren örnek:

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

Bildirimleri durdur

expiration mülkü, bildirimlerin ne zaman otomatik olarak duracağını kontrol eder. Belirli bir kanalın bildirimlerini, süresi dolmadan önce şu URI'de stop yöntemini çağırarak almayı durdurabilirsiniz:

https://www.googleapis.com/drive/v3/channels/stop

Bu yöntem için, aşağıdaki örnekte gösterildiği gibi en azından kanalın id ve resourceId özelliklerini sağlamanız gerekir. Google Drive API'de watch yöntemlerine sahip çeşitli türde kaynaklar varsa yalnızca bir stop yöntemi olduğunu unutmayın.

Yalnızca doğru izinlere sahip kullanıcılar bir kanalı durdurabilir. Özellikle:

  • Kanal normal bir kullanıcı hesabı tarafından oluşturulduysa yalnızca kanalın oluşturulduğu istemcide bulunan ve kanalın oluşturulduğu OAuth 2.0 istemci kimlikleriyle tanımlanan kullanıcı kanalın yayınını durdurabilir.
  • Kanal bir hizmet hesabı tarafından oluşturulduysa aynı müşterideki tüm kullanıcılar kanalı durdurabilir.

Aşağıdaki kod örneğinde, bildirimlerin nasıl durdurulacağı 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"
}