این سند نحوه استفاده از اعلانهای لحظهای را شرح میدهد که وقتی منبعی تغییر میکند به برنامهتان اطلاع میدهد.
نمای کلی
Google Drive API اعلانهای لحظهای ارائه میدهد که به شما امکان میدهد تغییرات منابع را پایش کنید. میتوانید از این ویژگی برای بهبود عملکرد برنامهتان استفاده کنید. این کار به شما امکان میدهد هزینههای اضافی شبکه و محاسبات مربوط به منابع نظرسنجی را برای تعیین اینکه آیا تغییر کردهاند یا نه حذف کنید. هرگاه منبع تحتنظارت تغییر کند، Google Drive API به برنامه شما اطلاع میدهد.
برای استفاده از اعلانهای لحظهای، باید دو کار انجام دهید:
نشانی وب گیرنده یا گیرنده فراخوانی «وبهوک» را راهاندازی کنید.
این یک سرور HTTPS است که پیامهای اعلان API را که هنگام تغییر منبع راهاندازی میشوند، مدیریت میکند.
برای هر نقطه پایانی منبعی که میخواهید تماشا کنید، یک (کانال اعلان) راهاندازی کنید.
کانال اطلاعات مسیریابی را برای پیامهای اعلان مشخص میکند. بهعنوان بخشی از راهاندازی کانال، باید نشانی وب خاصی را که میخواهید اعلانها را در آن دریافت کنید مشخص کنید. هرگاه منبع کانالی تغییر کند، Google Drive API پیام اعلانی را بهعنوان درخواست
POSTبه آن نشانی وب ارسال میکند.
درحالحاضر، Google Drive API از اعلانهای مربوط به تغییرات در
روشهای files و changes پشتیبانی میکند.
ایجاد کانالهای اعلان
برای درخواست اعلان لحظهای، باید برای هر منبعی که میخواهید پایش کنید، کانال اعلان راهاندازی کنید. پساز راهاندازی کانالهای اعلان، Google Drive API به برنامه شما اطلاع میدهد که هر منبع تحتنظارت تغییر کرده است.
درخواست تماشا کردن
هر منبع Google Drive API قابلتماشا دارای یک
روش watch مرتبط در URI با فرم زیر است:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
برای راهاندازی کانال اعلان برای پیامهای مربوط به تغییرات در منبعی خاص، درخواست POST را به روش watch برای آن منبع ارسال کنید.
هر کانال اعلان هم با کاربر خاصی مرتبط است و هم با منبع (یا مجموعهای از منابع) خاصی. درخواست watch
موفق نخواهد بود مگراینکه کاربر فعلی
یا حساب سرویس
مالک این منبع باشد یا اجازه دسترسی به آن را داشته باشد.
مثالها
نمونه کد زیر نحوه استفاده از منبع
channels را برای شروع تماشای تغییرات در یک منبع
files بااستفاده از روش
files.watch نشان میدهد:
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",
"type": "web_hook",
"address": "https://mydomain.com/notifications",
...
"token": "target=myApp-myFilesChannelDest",
"expiration": 1426325213000
}در بدنه درخواست، کانال id،
type را بهعنوان web_hook، و نشانی وب گیرنده را در
address ارائه دهید. همچنین میتوانید بهصورت اختیاری موارد زیر را ارائه دهید:
- یک
tokenبرای استفاده بهعنوان توکن کانال شما. - زمان
expirationبرحسب میلیثانیه برای زمان انقضای کانال درخواستی شما.
نمونه کد زیر نحوه استفاده از منبع
channels را برای شروع تماشا برای همه
changes بااستفاده از روش
changes.watch نشان میدهد:
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",
"type": "web_hook",
"address": "https://mydomain.com/notifications",
...
"token": "target=myApp-myChangesChannelDest",
"expiration": 1426325213000
}در بدنه درخواست، کانال id،
type را بهعنوان web_hook، و نشانی وب گیرنده را در
address ارائه دهید. همچنین میتوانید بهصورت اختیاری موارد زیر را ارائه دهید:
- یک
tokenبرای استفاده بهعنوان توکن کانال شما. - زمان
expirationبرحسب میلیثانیه برای زمان انقضای کانال درخواستی شما.
مشخصات الزامی
با هر درخواست watch، باید این فیلدها را ارائه دهید:
-
رشته ویژگی
idکه این کانال اعلان جدید را بهطور منحصربهفرد در پروژه شما شناسایی میکند. توصیه میکنیم از شناسه منحصربهفرد جهانی (UUID) یا هر رشته منحصربهفرد مشابهی استفاده کنید. حداکثر طول: ۶۴ نویسه.مقدار شناسهای که تنظیم میکنید در سرایند HTTP
X-Goog-Channel-Idهر پیام اعلانی که برای این کانال دریافت میکنید تکرار میشود. -
رشته خصوصیت
typeروی مقدارweb_hookتنظیم شده است. -
رشته ویژگی
addressکه روی نشانی وبی تنظیم شده است که اعلانهای این کانال اعلان را گوش میدهد و به آنها پاسخ میدهد. این نشانی وب برگشت تماس وبقلاب شما است و باید از HTTPS استفاده کند.توجه داشته باشید که Google Drive API فقط درصورتی میتواند به این نشانی HTTPS اعلان ارسال کند که گواهینامه SSL معتبری در سرور وب شما نصب شده باشد. گواهینامههای نامعتبر شامل موارد زیر است:
- گواهینامههای خودامضا.
- گواهینامههایی که توسط منبعی نامطمئن امضا شدهاند.
- گواهیهایی که لغو شدهاند.
- گواهینامههایی که موضوع آنها با نام میزبان هدف مطابقت ندارد.
مشخصات اختیاری
همچنین میتوانید این فیلدهای اختیاری را با درخواست
watch خود مشخص کنید:
-
یک ویژگی
tokenکه مقدار رشته دلخواهی را برای استفاده بهعنوان یک توکن کانال مشخص میکند. میتوانید از نشانهای کانال اعلان برای اهداف مختلفی استفاده کنید. برای مثال، میتوانید از این کد برای تأیید اینکه هر پیام ورودی برای کانالی است که برنامهتان ایجاد کرده است استفاده کنید (تا مطمئن شوید که اعلان جعل نشده است) یا پیام را براساس هدف این کانال به مقصد درست در برنامهتان هدایت کنید. حداکثر طول: ۲۵۶ نویسه.این کد در سرایند HTTP
X-Goog-Channel-Tokenدر هر پیام اعلانی که برنامه شما برای این کانال دریافت میکند گنجانده شده است.اگر از توکنهای کانال اعلان استفاده میکنید، توصیه میکنیم:
از قالب کدگذاری قابلگسترش، مثل پارامترهای پُرسمان نشانی وب، استفاده کنید. مثال:
forwardTo=hr&createdBy=mobileدادههای حساس مثل کدهای OAuth را وارد نکنید.
-
رشته ویژگی
expirationکه روی مُهر زمان Unix (برحسب میلیثانیه) تاریخ و زمانی تنظیم شده است که میخواهید Google Drive API ارسال پیام برای این کانال اعلان را متوقف کند.اگر کانال زمان انقضا داشته باشد، این زمان بهعنوان مقدار سرایند HTTP
X-Goog-Channel-Expiration(در قالب قابلخواندن برای انسان) در هر پیام اعلانی که برنامه شما برای این کانال دریافت میکند گنجانده میشود.
برای جزئیات بیشتر درباره درخواست، به روش watch
برای روشهای files و changes در «مرجع میانای برنامهسازی کاربردی» مراجعه کنید.
پاسخ ساعت
اگر درخواست watch با موفقیت کانال اعلان ایجاد کند،
رمز وضعیت HTTP 200 OK را برمیگرداند.
بدنه پیام پاسخ watch اطلاعاتی درباره کانال اعلانی که بهتازگی ایجاد کردهاید ارائه میدهد، همانطور که در مثال زیر نشان داده شده است.
{
"kind": "api#channel",
"id": "01234567-89ab-cdef-0123456789ab",
"resourceId": "o3hgv1538sdjfh",
"resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh",
"token": "target=myApp-myFilesChannelDest",
"expiration": 1426325213000
}
بدنه پاسخ جزئیات کانال را ارائه میدهد، مانند:
kind: این را بهعنوان منبع کانال API شناسایی میکند.id: شناسهای که برای این کانال مشخص کردهاید.-
resourceId: شناسه منبع تماشاشده. resourceUri: شناسه مختص نسخه منبع تحتنظر.-
token: کد ارائهشده در متن درخواست. expiration: زمان انقضای کانال بهعنوان مُهر زمان یونیکس به میلیثانیه.
علاوهبر ویژگیهایی که بهعنوان بخشی از درخواستتان ارسال کردید، اطلاعات برگرداندهشده شامل resourceId و resourceUri نیز میشود تا منبعی را که در این کانال اعلان تحت نظارت است شناسایی کند.
میتوانید اطلاعات برگرداندهشده را به سایر عملیات کانال اعلان منتقل کنید، مثلاً وقتی میخواهید دریافت اعلانها را متوقف کنید.
برای جزئیات بیشتر درباره پاسخ، به روش watch
برای روشهای files و changes در «مرجع میانای برنامهسازی کاربردی» مراجعه کنید.
پیام همگامسازی
پساز ایجاد کانال اعلان برای تماشای منبع،
Google Drive API پیام sync را ارسال میکند تا نشان دهد
اعلانها شروع میشوند. مقدار سرایند HTTP
X-Goog-Resource-State برای این پیامها sync است. بهدلیل مشکلات زمانبندی شبکه، ممکن است پیام sync را حتی قبلاز دریافت پاسخ روش watch دریافت کنید.
میتوانید اعلان sync را نادیده بگیرید، اما میتوانید از آن استفاده هم بکنید. برای مثال، اگر تصمیم گرفتید که نمیخواهید کانال را نگه دارید، میتوانید از مقادیر X-Goog-Channel-ID و X-Goog-Resource-ID در یک تماس برای توقف دریافت اعلانها استفاده کنید. همچنین میتوانید از اعلان
sync برای انجام برخیاز مقداردهیهای اولیه برای آماده شدن برای
رویدادهای بعدی استفاده کنید.
قالب پیامهای sync که Google Drive API به نشانی وب گیرنده شما ارسال میکند در زیر نشان داده شده است.
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
پیامهای همگامسازی همیشه مقدار سرصفحه HTTP X-Goog-Message-Number
1 دارند. هر اعلان بعدی برای این کانال دارای شماره پیامی است که بزرگتر از شماره قبلی است، اگرچه شماره پیامها متوالی نخواهد بود.
تمدید کانالهای اعلان
کانال اعلان میتواند زمان انقضا داشته باشد، با مقداری که یا براساس درخواست شما یا براساس محدودیتها یا پیشفرضهای داخلی Google Drive API تعیین میشود (از مقدار محدودکنندهتر استفاده میشود). زمان انقضای کانال، اگر وجود داشته باشد، بهعنوان یک مُهر زمان یونیکس (به میلیثانیه) در اطلاعات بازگرداندهشده توسط روش watch گنجانده میشود. علاوهبراین، تاریخ و زمان انقضا (در قالب قابلخواندن برای انسان) در هر پیام اعلانی که برنامه شما برای این کانال در سرایند HTTP X-Goog-Channel-Expiration دریافت میکند گنجانده شده است.
درحالحاضر، روش خودکاری برای تمدید کانال اعلان وجود ندارد. وقتی
کانالی به انقضای خود نزدیک میشود، باید آن را با فراخوانی
روش watch با کانال جدیدی جایگزین کنید. مثل همیشه، باید از مقدار یکتایی برای
ویژگی id کانال جدید استفاده کنید. توجه داشته باشید که احتمالاً
یک دوره زمانی «همپوشانی» وجود دارد که در آن دو کانال اعلان برای
یک منبع فعال هستند.
دریافت اعلانها
هرگاه منبع تحتنظارت تغییر کند، برنامه شما پیام اعلانی دریافت میکند که تغییر را شرح میدهد. Google Drive API این پیامها را بهصورت درخواستهای HTTPS POST به نشانی وبی که بهعنوان ویژگی address برای این کانال اعلان مشخص کردهاید ارسال میکند.
تفسیر قالب پیام اعلان
همه پیامهای اعلان شامل مجموعهای از سرایندهای HTTP هستند که پیشوند
X-Goog- دارند.
برخیاز انواع اعلانها میتوانند حاوی متن پیام نیز باشند.
سرصفحهها
پیامهای اعلانی که Google Drive API به نشانی وب گیرنده شما ارسال میکند شامل سرایندهای HTTP زیر است:
| سرایند | شرح |
|---|---|
| همیشه ارائه شود | |
|
UUID یا رشته منحصربهفرد دیگری که برای شناسایی این کانال اعلان ارائه کردهاید. |
|
عدد صحیحی که این پیام را برای این کانال اعلان شناسایی میکند. مقدار همیشه 1 برای پیامهای sync است. شماره پیامها برای هر پیام بعدی در کانال افزایش مییابد، اما این شمارهها متوالی نیستند. |
|
مقدار مبهمی که منبع تماشاشده را شناسایی میکند. این شناسه در نسخههای مختلف میانای برنامهسازی کاربردی ثابت است. |
|
وضعیت منبع جدیدی که اعلان را راهاندازی کرده است.
مقادیر ممکن:
sync، add، remove، update،
trash، untrash، یا change
.
|
|
شناسه مختص نسخه API برای منبع تماشاشده. |
| گاهی اوقات وجود دارد | |
|
جزئیات بیشتر درباره تغییرات.
مقادیر ممکن:
content،
parents،
children، یا
permissions
.
با پیامهای sync ارائه نشده است. |
|
تاریخ و زمان انقضای کانال اعلان، که در قالب قابلخواندن برای انسان بیان شده است. فقط درصورت تعریف شدن وجود دارد. |
|
نشان کانال اعلان که توسط برنامه شما تنظیم شده است و میتوانید از آن برای تأیید منبع اعلان استفاده کنید. فقط درصورت تعریف شدن وجود دارد. |
پیامهای اعلان برای هر دو منبع files (شامل
رویدادهای add، remove، update،
trash، و untrash) و
منابع changes همیشه خالی هستند (بدنه درخواست HTTP
خالی است، یعنی Content-Length: 0).
مثالها
پیام اعلان برای منابع files وقتی منبعی اضافه میشود (بدنه درخواست خالی است):
POST https://mydomain.com/notifications Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66 X-Goog-Channel-Token: 3a98f1a2b3c4d5e6f7 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: add X-Goog-Message-Number: 10
پیام اعلان را برای منابع files وقتی منبعی بهروز میشود تغییر دهید (بدنه درخواست خالی است):
POST https://mydomain.com/notifications Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66 X-Goog-Channel-Token: 3a98f1a2b3c4d5e6f7 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: 11
پیام اعلان تغییر برای منابع changes (بدنه درخواست خالی است):
POST https://mydomain.com/notifications Content-Type: application/json; utf-8 Content-Length: 0 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
پاسخ دادن به اعلانها
برای نشان دادن موفقیت، میتوانید هرکدام از رمزهای وضعیت زیر را برگردانید:
200، 201، 202، 204، یا
102.
اگر سرویس شما از کتابخانه کارخواه Google API استفاده میکند
و 500، 502، 503، یا 504 را برمیگرداند، Google Drive API
با عقبنشینی نمایی دوباره امتحان میکند.
هر کد وضعیت برگشتی دیگری بهعنوان عدم موفقیت پیام درنظر گرفته میشود.
آشنایی با رویدادهای اعلان Google Drive API
این بخش جزئیاتی درباره پیامهای اعلانی که میتوانید هنگام استفاده از اعلانهای لحظهای با Google Drive API دریافت کنید ارائه میدهد.
| زمان تحویل | ||
|---|---|---|
sync |
files، changes |
کانال باموفقیت ایجاد شد. میتوانید انتظار داشته باشید که دریافت اعلانهای آن را شروع کنید. |
add |
files |
منبعی ایجاد یا همرسانی شد. |
|
files |
منبع موجودی حذف شده یا همرسانی آن لغو شده است. |
|
files |
یک یا چند ویژگی (فراداده) منبع بهروز شده است. |
|
files |
منبعی به حذفشدهها منتقل شده است. |
|
files |
منبعی از حذفشدهها برداشته شد. |
|
changes |
یک یا چند مورد به گزارش تغییرات اضافه شده است. |
برای رویدادهای update، ممکن است سرایند HTTP X-Goog-Changed
ارائه شود. آن سرایند حاوی فهرستی جداشده با کاما است که
انواع تغییرات رخداده را شرح میدهد.
| نوع تغییر | نشان میدهد |
|---|---|
content |
محتوای منبع بهروز شده است. |
properties |
یک یا چند ویژگی منبع بهروزرسانی شده است. |
parents |
یک یا چند منبع اصلی اضافه یا حذف شده است. |
children |
یک یا چند منبع فرزند اضافه یا حذف شده است. |
permissions |
اجازههای منبع بهروزرسانی شده است. |
مثال با سرایند X-Goog-Changed:
X-Goog-Resource-State: update X-Goog-Changed: content, permissions
توقف اعلانها
ویژگی expiration کنترل میکند که اعلانها چه زمانی بهطور خودکار متوقف شوند. میتوانید
انتخاب کنید که دریافت اعلانها برای کانال خاصی را قبلاز
انقضای آن با فراخوانی روش stop در
شناسه منبع یکسان زیر متوقف کنید:
https://www.googleapis.com/drive/v3/channels/stop
این روش مستلزم آن است که حداقل ویژگیهای id و resourceId کانال را ارائه دهید، همانطور که در مثال زیر نشان داده شده است. توجه داشته باشید که اگر Google Drive API چندین نوع
منبع داشته باشد که دارای روشهای watch هستند، فقط یک
روش stop وجود دارد.
فقط کاربران دارای اجازه مناسب میتوانند کانال را متوقف کنند. بطور خاص:
- اگر کانال توسط یک حساب کاربری معمولی ایجاد شده باشد، فقط همان کاربری که کانال را ایجاد کرده است و از همان کارخواه (که توسط شناسههای کارخواه OAuth 2.0 از توکنهای احراز هویت شناسایی میشود) میتواند کانال را متوقف کند.
- اگر کانال توسط حساب سرویس ایجاد شده باشد، هر کاربری از همان کارخواه میتواند کانال را متوقف کند.
نمونه کد زیر نشان میدهد که چگونه دریافت اعلانها را متوقف کنید:
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"
}