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. Bu özelliği uygulamanızın performansını artırmak için kullanabilirsiniz. Değişip değişmediklerini belirlemek için yoklama kaynaklarıyla ilişkili ek ağ ve işlem maliyetlerini ortadan kaldırmanızı sağlar. İzlenen bir kaynak her değiştiğinde Google Drive API, uygulamanıza bildirim gönderir.
Push bildirimlerini kullanmak için yapmanız gereken iki şey vardır:
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 kurulumunun bir parçası olarak, bildirimleri almak istediğiniz belirli URL'yi belirtmeniz gerekir. Bir kanalın kaynağı her değiştiğinde, Google Drive API söz konusu URL'ye
POST
isteği olarak bir bildirim mesajı gönderir.
Şu anda Google Drive API, files
ve changes
yöntemlerindeki 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 bir kaynak değiştiğinde Google Drive API uygulamanızı bilgilendirir.
Saat isteği gönderme
Her bir izlenebilir Google Drive API kaynağının, aşağıdaki biçimdeki URI'da 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 POST
isteği gönderin.
Her bildirim kanalı hem belirli bir kullanıcıyla hem de belirli bir kaynakla (veya kaynak grubuyla) ilişkilidir. Geçerli kullanıcı veya hizmet hesabı bu kaynağa sahip değilse veya bu kaynağa erişim izni yoksa watch
istekleri başarılı olmaz.
Örnekler
Aşağıdaki kod örneğinde, tek bir files
kaynağında yapılan değişiklikleri files.watch
yöntemiyle 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, bir channels
kaynağının tüm changes
üyeleri için izlemeye başlamak üzere changes.watch
yöntemini kullanarak 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
ö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ış birtype
özellik dizesi. -
Bu bildirim kanalının bildirimlerini dinleyip yanıt veren URL'ye ayarlanmış bir
address
özellik dizesi. Bu sizin webhook geri çağırma URL'nizdir ve HTTPS kullanmalıdır.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ı şu alanları da belirtebilirsiniz:
-
Kanal jetonu olarak kullanılacak rastgele bir dize değeri belirten
token
mülkü. 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ğine maruz kalmadığından emin olmak veya bu kanalın amacına göre iletiyi 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 bilgisine eklenir.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.
-
expiration
mülk dizesi, Google Drive API'nin bu bildirim kanalı için mesaj göndermeyi durdurmasını istediğiniz tarih ve saatin Unix zaman damgasına (milisaniye cinsinden) 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 değeri (insanlar tarafından okunabilir biçimde) olarak eklenir.
İstek hakkında daha fazla bilgi için API Referansı'ndaki files
ve changes
yöntemleriyle ilgili watch
yöntemini inceleyin.
Yanıtı izle
watch
isteği başarıyla bildirim kanalı oluşturursa 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. }
Talebinizin bir parçası olarak gönderdiğiniz özelliklere ek olarak, döndürülen bilgiler bu bildirim kanalında izlenen kaynağı tanımlamak için resourceId
ve resourceUri
özelliklerini de içerir.
İade edilen bilgileri, örneğin bildirim almayı durdurmak istemeniz gibi diğer bildirim kanalı işlemlerine iletebilirsiniz.
Yanıt hakkında daha ayrıntılı bilgi için API Referansı'ndaki files
ve changes
yöntemleri için watch
yöntemine bakın.
Mesajı senkronize et
Bir kaynağı izlemek için bildirim kanalı oluşturulduktan sonra Google Drive API, 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 bildirimi de kullanabilirsiniz. Örneğin, kanalı kullanmaya devam etmek 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ının X-Goog-Message-Number
HTTP üst bilgisi değeri her zaman 1
olur. Bu kanal için sonraki her bildirimde, öncekinden daha büyük bir mesaj numarası bulunur ancak mesaj numaraları sıralı değildir.
Bildirim kanallarını yenile
Bildirim kanalının bir son kullanma zamanı olabilir. Bu süre, isteğinize veya Google Drive API'lerinin dahili sınırlarına ya da varsayılanlarına göre 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, uygulamanızın bu kanal için aldığı her bildirim mesajına son kullanma tarihi ve saati (kullanıcıların okuyabileceği biçimde) X-Goog-Channel-Expiration
HTTP başlığında belirtilir.
Şu anda, bildirim kanalları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ının etkin olduğu zaman dilimlerinin "örtüşme" 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ı HTTPS POST
istekleri olarak, bu bildirim kanalı için address
mülkü olarak belirttiğiniz URL'ye gönderir.
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
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 | |
|
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ı. sync mesajları için değer her zaman 1 şeklindedir. Kanalda gösterilen her mesajın sayısı artar ancak bu sayılar sıralı değildir. |
|
İzlenen kaynağı tanımlayan opak bir değerdir. Bu kimlik, tüm API sürümlerinde 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 mevcut | |
|
Değişikliklerle ilgili ek ayrıntılar.
Olası değerler:
content ,
parents ,
children veya
permissions
.
sync mesajlarıyla birlikte sağlanmadı. |
|
Bildirim kanalının sona erme tarihi ve saati. Kullanıcıların okuyabileceği biçimde belirtilir. Yalnızca tanımlanmışsa mevcut. |
|
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övdesi 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ır ve 500
,502
, 503
veya 504
değerini döndürürse Google Drive API, üstel geri yükleme ile yeniden dener.
Diğer tüm iade durum kodları, mesaj 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ıyla ilgili ayrıntılar yer almaktadır.
Teslimat zamanı | ||
---|---|---|
sync |
files , changes |
Bir kanal başarıyla oluşturuldu. Uygulamayla 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 verileri) güncellendi. |
|
files |
Bir kaynak çöp kutusuna taşındı. |
|
files |
Çöp kutusundan bir kaynak 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ık, gerçekleşen değişikliklerin türlerini açıklayan virgülle ayrılmış bir liste içerir.
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 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. Aşağıdaki URI'da stop
yöntemini çağırarak belirli bir kanal için bildirim almayı süresi dolmadan önce durdurmayı seçebilirsiniz:
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'nin watch
yöntemlerine sahip ç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 bir kanalı durdurabilir. Özellikle:
- Kanal normal bir kullanıcı hesabı tarafından oluşturulduysa yalnızca aynı istemcideki aynı kullanıcı (yetkilendirme jetonlarındaki OAuth 2.0 istemci kimlikleri ile tanımlanır) kanalı durdurabilir.
- Kanal bir hizmet hesabı tarafından oluşturulmuşsa 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" }