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 | |
|
Bu bildirim kanalını tanımlamak için sağladığınız UUID veya başka bir benzersiz dize. |
|
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. |
|
İzlenen kaynağı tanımlayan opak bir değer. Bu kimlik, API sürümleri genelinde sabittir. |
|
Bildirimi tetikleyen yeni kaynak durumu.
Olası değerler:
sync , add , remove , update ,
trash , untrash veya change
.
|
|
İzlenen kaynak için API sürümüne özgü bir tanımlayıcı. |
Bazen mevcuttur | |
|
Değişikliklerle ilgili ek ayrıntılar.
Muhtemel değerler:
content ,
parents ,
children veya
permissions
.
sync mesajlarıyla sağlanmadı. |
|
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. |
|
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.
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ı. |
|
files |
Mevcut bir kaynak silindi veya paylaşımı geri alındı. |
|
files |
Bir kaynağın en az bir özelliği (meta veriler) güncellenmiştir. |
|
files |
Bir kaynak çöp kutusuna taşındı. |
|
files |
Bir kaynak, çöp kutusundan kaldırıldı. |
|
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" }