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 izlemenize olanak tanıyan push bildirimleri sunar. Uygulamanızın performansını iyileştirmek için bu özelliği kullanabilirsiniz. Bu sayede, değişip değişmediğini belirlemek için yoklama kaynaklarının gerektirdiği ek ağ ve işlem maliyetlerini ortadan kaldırabilirsiniz. İzlenen bir kaynak değiştiğinde, Google Drive API uygulamanızı bilgilendirir.

Push bildirimlerini 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.

    Bir kanal, bildirim mesajları için yönlendirme bilgilerini belirtir. Kanal kurulumu kapsamında, bildirimleri almak istediğiniz belirli URL'yi belirtmeniz gerekir. Bir kanalın kaynağı değiştiğinde, Google Drive API bu URL'ye POST isteği olarak bir bildirim mesajı gönderir.

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

Bildirim kanalları oluşturma

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

İzleme isteğinde bulunma

Her izlenebilir Google Drive API kaynağının URI'sinde aşağıdaki biçimde ilişkili bir watch yöntemi bulunur:

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 kaynak için watch yöntemine POST isteği gönderin.

Her bildirim kanalı, hem belirli bir kullanıcı hem de belirli bir kaynak (veya kaynak grubu) ile ilişkilendirilir. Geçerli kullanıcı veya hizmet hesabı bu kaynağa sahip olmadığı ya da erişim iznine sahip olmadığı sürece watch isteği başarılı olmaz.

Ö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:

  • Projenizdeki bu yeni bildirim kanalını benzersiz şekilde tanımlayan bir id özellik dizesi. Evrensel olarak benzersiz bir tanımlayıcı (UUID) veya benzer herhangi 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 başlığında tekrarlanır.

  • type özellik dizesi, web_hook değerine ayarlandı.

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

    Google Drive API'nin, yalnızca web sunucunuzda geçerli bir SSL sertifikası yüklüyse bu HTTPS adresine 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 ş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 adres sahteciliğinde gönderilmediğinden emin olmak veya mesajı, bu kanalın amacına göre uygulamanızdaki doğru hedefe yönlendirmek için bu jetonu kullanabilirsiniz. Maksimum uzunluk: 256 karakter.

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

    Bildirim kanalı jetonlarını 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 özellik dizesi, Google Drive API'nin bu bildirim kanalı için mesaj göndermeyi durdurmasını istediğiniz tarih ve saati içeren bir 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ına X-Goog-Channel-Expiration HTTP üst bilgisinin (kullanıcılar tarafından okunabilir biçimde) değeri olarak eklenir.

İstek hakkında daha fazla bilgi için API Referansı'ndaki files ve changes yöntemleriyle ilgili watch yöntemine göz atın.

Yanıtı izle

watch isteği başarıyla bir bildirim kanalı oluşturursa HTTP 200 OK durum kodu döndürü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": "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.
}

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 özelliklerini de içerir.

Döndürülen bilgileri, bildirim almayı durdurmak istediğiniz zamanlar gibi diğer bildirim kanalı işlemlerine aktarabilirsiniz.

Yanıt hakkında daha ayrıntılı bilgi için API Referansı'ndaki files ve changes yöntemleriyle ilgili watch yöntemine göz atın.

İletiyi senkronize et

Bir kaynağı izlemek için bildirim kanalı oluşturulduktan sonra Google Drive API, bildirimlerin başladığını bildiren 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 sync mesajını almanız mümkündür.

sync bildirimini yoksayabilirsiniz ancak bunu da kullanabilirsiniz. Örneğin, kanalı tutmak istemezseniz bildirim almayı durdurmak için aramada X-Goog-Channel-ID ve X-Goog-Resource-ID değerlerini kullanabilirsiniz. Daha sonraki etkinliklere hazırlanmak amacıyla bazı başlatma işlemleri için 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 üst bilgisi her zaman 1 olur. Bu kanal için takip eden her bildirimde, öncekinden daha büyük bir mesaj numarası bulunur ancak mesaj numaraları sıralı değildir.

Bildirim kanallarını yenile

Bir bildirim kanalının son geçerlilik tarihi olabilir. Bu süre, isteğiniz veya Google Drive API'sinin dahili sınırları ya da varsayılan değeri (daha kısıtlayıcı olan değer kullanılır) tarafından belirlenir. Kanalın geçerlilik süresi varsa (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 yenilemenin bir yolu yoktur. Bir kanalın kullanım süresi dolmak üzereyken 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ının etkin olduğu durumlarda, bir "örtüşme" süresinin olabileceğini unutmayın.

Bildirim al

İzlenen bir kaynak değiştiğinde, uygulamanız değişikliği açıklayan bir bildirim mesajı alır. Google Drive API, bu mesajları bu bildirim kanalı için 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'si tarafından alıcı URL'nize gönderilen bildirim mesajları, aşağıdaki HTTP üstbilgilerini 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 mesaj için her zaman 1 şeklindedir. Kanalda takip eden her mesaj için mesaj numaraları artar ancak bu mesajlar sıralı değildir.
X-Goog-Resource-ID İzlenen kaynağı tanımlayan opak bir değer. Bu kimlik, API sürümleri genelinde sabittir.
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. Muhtemel değerler: content, parents, children veya permissions . sync mesajlarıyla sağlanmadı.
X-Goog-Channel-Expiration Bildirim kanalının geçerlilik süresinin sona erme tarihi ve saati (kullanıcılar tarafından okunabilir biçimde belirtilir). Yalnızca tanımlanmışsa mevcuttur.
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 mevcut olur.

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 500,502, 503 veya 504 değerini döndürürse Google Drive API, eksponansiyel geri yükleme ile yeniden dener. Diğer tüm iade durum kodları, mesaj hatası olarak değerlendirilir.

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 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. Belirli bir kanal için bildirim almayı, süresi dolmadan önce durdurmak için aşağıdaki URI'da stop yöntemini çağırabilirsiniz:

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

Bu yöntem, aşağıdaki örnekte gösterildiği gibi en azından kanalın id ve resourceId özelliklerini sağlamanızı gerektirir. Google Drive API'de watch yöntemleri olan çeşitli kaynak türleri varsa sadece bir stop yöntemi olduğunu unutmayın.

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

  • Kanal normal bir kullanıcı hesabı tarafından oluşturulduysa yalnızca aynı istemcideki kanalı oluşturan kullanıcı (yetkilendirme jetonlarından OAuth 2.0 istemci kimlikleri tarafından tanımlandığı şekilde) kanalı durdurabilir.
  • Kanal bir hizmet hesabı tarafından oluşturulduysa aynı istemcideki 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"
}