اعلان‌های مربوط به تغییرات منبع

این سند نحوه استفاده از اعلان‌های لحظه‌ای را شرح می‌دهد که وقتی منبعی تغییر می‌کند به برنامه‌تان اطلاع می‌دهد.

نمای کلی

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 زیر است:

سرایند شرح
همیشه ارائه شود
X-Goog-Channel-ID UUID یا رشته منحصربه‌فرد دیگری که برای شناسایی این کانال اعلان ارائه کرده‌اید.
X-Goog-Message-Number عدد صحیحی که این پیام را برای این کانال اعلان شناسایی می‌کند. مقدار همیشه 1 برای پیام‌های sync است. شماره پیام‌ها برای هر پیام بعدی در کانال افزایش می‌یابد، اما این شماره‌ها متوالی نیستند.
X-Goog-Resource-ID مقدار مبهمی که منبع تماشاشده را شناسایی می‌کند. این شناسه در نسخه‌های مختلف میانای برنامه‌سازی کاربردی ثابت است.
X-Goog-Resource-State وضعیت منبع جدیدی که اعلان را راه‌اندازی کرده است. مقادیر ممکن: sync، add، remove، update، trash، untrash، یا change .
X-Goog-Resource-URI شناسه مختص نسخه API برای منبع تماشاشده.
گاهی اوقات وجود دارد
X-Goog-Changed جزئیات بیشتر درباره تغییرات. مقادیر ممکن: content، parents، children، یا permissions . با پیام‌های sync ارائه نشده است.
X-Goog-Channel-Expiration تاریخ و زمان انقضای کانال اعلان، که در قالب قابل‌خواندن برای انسان بیان شده است. فقط درصورت تعریف شدن وجود دارد.
X-Goog-Channel-Token نشان کانال اعلان که توسط برنامه شما تنظیم شده است و می‌توانید از آن برای تأیید منبع اعلان استفاده کنید. فقط درصورت تعریف شدن وجود دارد.

پیام‌های اعلان برای هر دو منبع 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 دریافت کنید ارائه می‌دهد.

X-Goog-Resource-State اعمال می‌شود در زمان تحویل
sync files، changes کانال باموفقیت ایجاد شد. می‌توانید انتظار داشته باشید که دریافت اعلان‌های آن را شروع کنید.
add files منبعی ایجاد یا هم‌رسانی شد.
remove files منبع موجودی حذف شده یا هم‌رسانی آن لغو شده است.
update files یک یا چند ویژگی (فراداده) منبع به‌روز شده است.
trash files منبعی به حذف‌شده‌ها منتقل شده است.
untrash files منبعی از حذف‌شده‌ها برداشته شد.
change 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"
}