Kaynak değişiklikleriyle ilgili bildirimler

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

Genel bakış

Google Drive API, kaynaklardaki değişiklikleri izlemenize olanak tanıyan push bildirimleri sağlar. Uygulamanızın performansını iyileştirmek için bu özelliği kullanabilirsiniz. Değişip değişip değişmediğini belirlemek için yoklama kaynaklarıyla ilgili ek ağ ve işlem maliyetlerini ortadan kaldırmanızı sağlar. İzlenen bir kaynak her değiştiğinde, Google Drive API'si 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 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 belirli 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.

Not: Bu belgede kullanılan "kanal" kelimesi özellikle bildirim kanalını ifade eder, bu API'de veya hizmette kullanılan diğer kanal türlerini ifade etmez.

Ş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 üzere 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'si uygulamanızı bilgilendirir.

İzleme isteğinde bulun

İzlenebilir her Google Drive API kaynağının, aşağıdaki biçimdeki 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şiklikler hakkındaki mesajlar için bildirim kanalı oluşturmak isterseniz kaynağın watch yöntemine POST isteği gönderin.

Her bildirim kanalı hem belirli bir kullanıcıyla hem de belirli bir kaynakla (veya kaynak grubuyla) ilişkilendirilir. Geçerli kullanıcı veya hizmet hesabı bu kaynağa sahip değilse ya da bu kaynağa erişim izni yoksa watch isteği başarılı olmaz.

Örnekler

Aşağıdaki kod örneğinde, tek bir files kaynağında files.watch yöntemi kullanılarak yapılan 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 kanalının tamamı için changes.watch yöntemini kullanarak izlemeye başlamak üzere 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 aşağıdaki alanları sağlamanız gerekir:

• Projeniz içinde bu yeni bildirim kanalını benzersiz şekilde tanımlayan bir id özellik 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 üst bilgisinde tekrarlanır.

• web_hook değerine ayarlanmış type özelliği dizesi.

• address mülk dizesi, bu bildirim kanalının bildirimlerini dinleyip bunlara yanıt veren URL'ye ayarlanır. Bu sizin webhook geri çağırma URL'nizdir ve HTTPS kullanması gerekir.

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

watch isteğinizle isteğe bağlı olarak şu alanları da belirtebilirsiniz:

• Kanal jetonu olarak kullanılacak rastgele bir dize değeri belirten token özelliği. Bildirim kanalı jetonlarını çeşitli amaçlar için kullanabilirsiniz. Örneğin, jetonu kullanarak gelen her iletinin uygulamanızın oluşturduğu bir kanala ait olduğunu doğrulayıp bildirimin adres sahteciliğine maruz kalmadığından emin olabilir veya iletiyi, bu kanalın amacı doğrultusunda uygulamanızdaki doğru hedefe yönlendirebilirsiniz. Maksimum uzunluk: 256 karakter.

  Jeton, uygulamanızın bu kanal için aldığı her bildirim mesajında X-Goog-Channel-Token HTTP üst bilgisine dahil edilir.

  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.

  Not: Son derece hassas veriler göndermeniz gerekiyorsa bu verileri jetona eklemeden önce şifrelendiğinden emin olun.

• expiration mülk 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ına (milisaniye cinsinden) ayarlanır.

  Bir kanalın geçerlilik süresi varsa uygulamanızın bu kanal için aldığı her bildirim mesajına X-Goog-Channel-Expiration HTTP üst bilgisinin değeri (insanlar tarafından okunabilir biçimde) olarak eklenir.

Not: Google Drive API'de maksimum geçerlilik süresi, files kaynağı için geçerli zamandan sonra 86.400 saniye (1 gün) ve changes için 604.800 saniyedir (1 hafta). İsteğinizde expiration özelliğini ayarlamazsanız geçerlilik süresi varsayılan olarak geçerli zamandan 3.600 saniye sonra olur.

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

Yanıtı izle

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

Saat 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.
}

İ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 de bulunur.

Not: resourceId özelliği, kaynağın sabit ve sürümden bağımsız bir tanımlayıcısıdır. resourceUri özelliği, geçerli API sürümü bağlamında izlenen kaynağın standart URI'sıdır. Bu nedenle sürüme özgüdür.

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

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

İletiyi senkronize et

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 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 bile sync mesajını alabilirsiniz.

sync bildirimini güvenle yoksayabilirsiniz, ancak bunu da kullanabilirsiniz. Örneğin, kanalı tutmak istemediğinize karar verirseniz bir çağrıda 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.

Google Drive API'nin alıcı URL'nize gönderdiği sync mesajlarının biçimi aşağıda gösterilmektedir.

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ı her zaman 1 X-Goog-Message-Number HTTP üst bilgi değerine sahiptir. Bu kanal için bir sonraki bildirimde, öncekinden daha büyük bir mesaj numarası vardır ancak mesaj numaraları sıralı değildir.

Bildirim kanallarını yenile

Bildirim kanalının bir geçerlilik süresi olabilir. Bu süre, isteğiniz veya Google Drive API dahili sınırları ya da varsayılan değerleri tarafından belirlenen bir değerdir (daha kısıtlayıcı değer kullanılır). Kanalın geçerlilik süresi (varsa) watch yöntemi tarafından döndürülen bilgilere Unix zaman damgası (milisaniye cinsinden) olarak eklenir. Buna ek olarak, geçerlilik bitiş tarihi ve saati, uygulamanızın bu kanal için X-Goog-Channel-Expiration HTTP üst bilgisinde aldığı her bildirim mesajına eklenir (kullanıcıların okuyabileceği biçimde).

Şu anda bir bildirim kanalını yenilemenin otomatik bir yolu yoktur. Bir kanalın geçerlilik bitiş tarihi yaklaştığında, 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ı etkin olduğunda "çakışan" bir süre olabileceğini unutmayın.

Bildirim al

İ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ı bu bildirim kanalı için address mülkü olarak belirttiğiniz URL'ye HTTPS POST istekleri olarak gönderir.

Not: Bildirim gönderme HTTPS istekleri, APIs-Google kullanıcı aracısını belirtir ve Google Kullanıcı Aracısı API'leri bölümünde açıklandığı gibi robots.txt yönergelerine uyar.

Bildirim mesajı biçimini yorumlama

Tüm bildirim mesajları, X-Goog- ön eklerine sahip bir grup HTTP üst bilgisi içerir. Bazı bildirim türleri, mesaj gövdesi de içerebilir.

Üst bilgiler

Alıcı URL'nize Google Drive API tarafından gönderilen bildirim mesajları, aşağıdaki HTTP üst bilgilerini içerir:

Başlık	Açıklama
Her zaman göster
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ı. sync mesajları için değer her zaman 1 olur. Kanalda gösterilen her mesajda mesaj sayısı artar ancak bu sayılar sıralı değildir.
X-Goog-Resource-ID	İzlenen kaynağı tanımlayan opak bir değerdir. Bu kimlik, API sürümlerinde 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 gösterilir
X-Goog-Changed	Değişikliklerle ilgili ek ayrıntılar. Olası değerler: content, parents, children veya permissions . sync mesajlarla sağlanmadı.
X-Goog-Channel-Expiration	Bildirim kanalının süresinin dolma tarihi ve saati (kullanıcıların okuyabileceği biçimde belirtilir). Yalnızca tanımlanmışsa mevcut.
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 mevcuttur.

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

Örnekler

İstek metni 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 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

İşlemin başarılı olduğunu belirtmek için şu 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 yükleme ile yeniden deneme gerçekleştirir. Diğer tüm iade durum kodları bir 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ıyla ilgili ayrıntılar sunulmaktadır.

X-Goog-Resource-State	Geçerlilik kapsamı	Teslim zamanı:
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 verileri) güncellendi.
trash	files	Bir kaynak çöp kutusuna taşındı.
untrash	files	Çöp kutusundan bir kaynak kaldırıldı.
change	changes	Bir veya daha fazla değişiklik günlüğü öğesi eklendi.

Zaman içinde bu listeye başka kaynak durumu etkinlikleri eklenebilir. Beklenmedik türde etkinlikler alabilirsiniz. Etkinlik işleyicileriniz bunları sorunsuz bir şekilde yoksaymalıdır.

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

Değişiklik türü	Şunları 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 kaynak alt öğesi eklendi ya da kaldırıldı.
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 özelliği, bildirimlerin ne zaman otomatik olarak duracağını kontrol eder. Belirli bir kanal için bildirim almayı, süresi dolmadan önce durdurmayı seçebilirsiniz. Bunun 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'sinde watch yöntemleri olan birkaç kaynak türü varsa yalnızca bir stop yöntemi vardır.

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

• Kanal normal bir kullanıcı hesabı tarafından oluşturulmuşsa yalnızca kanalı oluşturan aynı istemcideki kullanıcı (yetkilendirme jetonlarındaki OAuth 2.0 istemci kimlikleriyle tanımlanır) 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"
}