Kaynak değişiklikleriyle ilgili bildirimler

Bu belgede, 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 izlemenizi sağlayan push bildirimleri sunar. Bu özelliği, uygulamanızın performansını artırmak için kullanabilirsiniz. Kaynakların değişip değişmediğini belirlemek için kaynakları yoklamayla ilişkili ek ağ ve işlem maliyetlerini ortadan kaldırmanıza olanak tanır. İzlenen bir kaynak her değiştiğinde Google Drive API, uygulamanızı bilgilendirir.

Push bildirimlerini kullanmak için iki işlem 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 bildirimi 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 sırasında, bildirimleri almak istediğiniz URL'yi belirtmeniz gerekir. Bir kanalın kaynağı her değiştiğinde Google Drive API, bu URL'ye POST isteği olarak bir bildirim mesajı gönderir.

Google Drive API şu anda files ve changes yöntemlerindeki değişikliklerle ilgili bildirimleri desteklemektedir.

Bildirim kanalları oluşturma

Push bildirimi isteğinde bulunmak için izlemek istediğiniz her kaynak için bir bildirim kanalı oluşturmanız gerekir. Bildirim kanallarınız ayarlandıktan sonra, Google Drive API, izlenen herhangi bir kaynak değiştiğinde uygulamanızı bilgilendirir.

İzleme istekleri oluşturma

İzlenebilir her Google Drive API kaynağıyla ilişkili bir watch yöntemi bulunur. Bu yöntemin URI'si aşağıdaki biçimdedir:

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 üzere kaynağın POST yöntemine watch 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, channels kaynağının files.watch yöntemi kullanılarak tek bir files kaynağındaki değişiklikleri izlemeye başlamak için 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 için izlemeyi başlatmak üzere 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ğinde şu alanları sağlamanız gerekir:

  • Projenizdeki 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.

    Ayarladığınız kimlik değeri, bu kanal için aldığınız her bildirim mesajının X-Goog-Channel-Id HTTP üstbilgisinde tekrar gösterilir.

  • type özelliği, web_hook değerine ayarlanmış bir dize.

  • Bu bildirim kanalı için bildirimleri dinleyen ve yanıtlayan URL'ye ayarlanmış bir address özellik dizesi. Bu, webhook geri çağırma URL'nizdir ve HTTPS kullanmalıdır.

    Google Drive API'nin bu HTTPS adresine yalnızca web sunucunuza 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

Ayrıca, 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 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 için (bildirimin sahte olmamasını sağlamak için) veya bu kanalın amacına göre mesajı uygulamanızdaki doğru hedefe yönlendirmek için jetonunu kullanabilirsiniz. Maksimum uzunluk: 256 karakter.

    Jeton, uygulamanızın bu kanal için aldığı her bildirim iletisindeki X-Goog-Channel-Token HTTP üstbilgisinde yer alır.

    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.

  • Google Drive API'nin bu bildirim kanalı için mesaj göndermeyi durdurmasını istediğiniz tarih ve saatin expiration özelliği, Unix zaman damgası (milisaniye cinsinden) olarak ayarlanır.

    Bir kanalın geçerlilik süresi varsa bu süre, uygulamanızın bu kanal için aldığı her bildirim mesajında X-Goog-Channel-Expiration HTTP üstbilgisinin değeri olarak (insan tarafından okunabilir biçimde) yer alır.

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

Saat yanıtı

watch isteği başarılı bir şekilde bildirim kanalı oluşturursa HTTP 200 OK durum kodunu döndürü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 bilgiler yer alı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.
}

İ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 da yer alır.

Döndürülen bilgileri, bildirim almayı durdurmak istediğinizde olduğu gibi diğer bildirim kanalı işlemlerine iletebilirsiniz.

Yanıt hakkında daha fazla bilgi için API Referansı'ndaki files ve changes yöntemlerinin watch yöntemine bakın.

İletileri senkronize etme

Bir kaynağı izlemek için bildirim kanalı oluşturduktan sonra Google Drive API, bildirimlerin başladığını belirten bir sync mesajı gönderir. Bu mesajlar için X-Goog-Resource-State HTTP başlığı değeri sync'dir. Ağ zamanlaması sorunları nedeniyle, watch yöntemi yanıtını almadan önce sync mesajını alabilirsiniz.

sync bildirimini dikkate almayabilirsiniz ancak bu bildirimi kullanmanız da mümkündür. Örneğin, kanalı tutmak istemediğinize karar verirseniz bildirim almayı durdurmak için yapılan bir çağrıda X-Goog-Channel-ID ve X-Goog-Resource-ID değerlerini kullanabilirsiniz. Ayrıca, daha sonraki etkinliklere hazırlanmak için bazı başlatma işlemlerini 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

Senkronize edilen mesajların X-Goog-Message-Number HTTP başlık değeri her zaman 1 olur. Bu kanal için sonraki her bildirimde, önceki bildirimden daha büyük bir mesaj numarası bulunur. Ancak mesaj numaraları sıralı olmaz.

Bildirim kanallarını yenileme

Bildirim kanallarının, isteğiniz veya Google Drive API'nin dahili sınırları ya da varsayılan değerleri (daha kısıtlayıcı değer kullanılır) tarafından belirlenen bir son kullanma tarihi olabilir. Kanalın varsa geçerlilik bitiş zamanı, watch yöntemi tarafından döndürülen bilgilerde Unix zaman damgası (milisaniye cinsinden) olarak yer alır. Ayrıca, son kullanma tarihi ve saati (insan tarafından okunabilir biçimde) uygulamanızın bu kanal için aldığı her bildirim mesajında X-Goog-Channel-Expiration HTTP üstbilgisinde yer alır.

Şu anda bildirim kanallarını otomatik olarak yenilemenin bir yolu yoktur. Bir kanalın süresi dolmak üzereyken watch yöntemini çağırarak bu kanalı yenisiyle 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ğın iki bildirim kanalının etkin olduğu bir "çakışma" süresinin olabileceğini unutmayın.

Bildirimleri alma

İzlenen bir kaynak her değiştiğinde uygulamanız, değişikliği açıklayan bir bildirim mesajı alır. Google Drive API, bu mesajları HTTPS POST istekleri olarak, bu bildirim kanalı için address özelliği olarak belirttiğiniz URL'ye gönderir.

Bildirim mesajı biçimini yorumlama

Tüm bildirim iletileri, X-Goog- öneklerine sahip bir dizi HTTP üstbilgisi içerir. Bazı bildirim türleri mesaj gövdesi de içerebilir.

Üst bilgiler

Google Drive API'nin alıcı URL'nize gönderdiği 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 diğer benzersiz dize.
X-Goog-Message-Number Bu bildirim kanalında bu mesajı tanımlayan tam sayı. Değer, sync mesajları için her zaman 1'dır. İleti numaraları, kanaldaki her sonraki ileti için artar ancak sıralı değildir.
X-Goog-Resource-ID İzlenen kaynağı tanımlayan opak değer. Bu kimlik, API sürümleri arasında kararlıdı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 kaynağın API sürümüne özgü tanımlayıcısı.
Bazen mevcut
X-Goog-Changed Değişikliklerle ilgili ek ayrıntılar. Olası değerler: content, parents, children veya permissions . sync iletilerinde sağlanmaz.
X-Goog-Channel-Expiration Bildirim kanalının geçerlilik bitiş tarihi ve saati, 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 için 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

İstek gövdesi içeren changes kaynakları için değişiklik bildirimi 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 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 Google Drive API üstel geri çekilme ile yeniden dener. Diğer tüm iade durumu kodları, ileti hatası olarak kabul edilir.

Google Drive API bildirim etkinliklerini anlama

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

X-Goog-Resource-State Geçerlilik kapsamı Teslim edildiği zaman
sync files, changes Bir kanal başarıyla oluşturuldu. Bu konuyla ilgili bildirim almaya başlayabilirsiniz.
add files Bir kaynak oluşturuldu veya paylaşıldı.
remove files Mevcut bir kaynak silindi veya paylaşımı kaldırıldı.
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 üstbilgisi 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ü Gösterir
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 eklenmiş veya kaldırılmış.
children Bir veya daha fazla kaynak alt öğesi eklendi veya kaldırıldı.
permissions Kaynak izinleri güncellendi.

X-Goog-Changed üstbilgisi içeren örnek:

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

Bildirimleri durdur

expiration özelliği, bildirimlerin otomatik olarak ne zaman durdurulacağını kontrol eder. Aşağıdaki URI'yi kullanarak stop yöntemini çağırarak belirli bir kanal için bildirim almayı durdurmayı seçebilirsiniz: <0

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

Bu yöntemde, 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öntemleri olan çeşitli kaynak türleri varsa yalnızca bir stop yöntemi olduğunu unutmayın.

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

  • Kanal normal bir kullanıcı hesabı tarafından oluşturulduysa kanalı yalnızca aynı istemciden (yetkilendirme jetonlarındaki OAuth 2.0 istemci kimlikleriyle tanımlandığı şekilde) aynı kullanıcı durdurabilir.
  • Kanal bir hizmet hesabı tarafından oluşturulduysa aynı müşteriden 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/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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