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

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

نمای کلی

Google Drive API اعلان‌های فشاری را ارائه می‌کند که به شما امکان می‌دهد تغییرات منابع را نظارت کنید. می توانید از این ویژگی برای بهبود عملکرد برنامه خود استفاده کنید. این به شما امکان می دهد شبکه اضافی را حذف کنید و هزینه های مربوط به منابع نظرسنجی را محاسبه کنید تا مشخص کنید آیا تغییر کرده اند یا خیر. هر زمان که یک منبع تماشا شده تغییر کند، API Google Drive به برنامه شما اطلاع می دهد.

برای استفاده از اعلان‌های فشاری، باید دو کار انجام دهید:

  • URL دریافتی خود یا گیرنده پاسخ به تماس "webhook" را تنظیم کنید.

    این یک سرور HTTPS است که پیام‌های اعلان API را که هنگام تغییر یک منبع فعال می‌شوند، مدیریت می‌کند.

  • برای هر نقطه پایانی منبعی که می خواهید تماشا کنید ( کانال اطلاع رسانی ) تنظیم کنید.

    یک کانال اطلاعات مسیریابی پیام های اعلان را مشخص می کند. به عنوان بخشی از راه‌اندازی کانال، باید URL خاصی را که می‌خواهید اعلان‌ها را دریافت کنید، شناسایی کنید. هر زمان که منبع کانال تغییر کند، Google Drive API یک پیام اعلان به عنوان یک درخواست POST به آن URL ارسال می کند.

در حال حاضر، 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", // 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.
}

نمونه کد زیر نحوه استفاده از یک منبع 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", // 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.
}

خواص مورد نیاز

با هر درخواست watch ، باید این فیلدها را ارائه دهید:

  • یک رشته ویژگی id که به طور منحصر به فرد این کانال اعلان جدید را در پروژه شما شناسایی می کند. توصیه می کنیم از یک شناسه منحصر به فرد جهانی ( UUID ) یا هر رشته منحصر به فرد مشابهی استفاده کنید. حداکثر طول: 64 کاراکتر.

    مقدار شناسه ای که تنظیم کرده اید در سرصفحه HTTP X-Goog-Channel-Id هر پیام اعلانی که برای این کانال دریافت می کنید بازتاب می یابد.

  • یک type رشته ویژگی با مقدار web_hook تنظیم شده است.

  • یک رشته ویژگی address روی URL تنظیم شده است که به اعلان‌های این کانال اعلان گوش می‌دهد و به آن پاسخ می‌دهد. این URL پاسخ به تماس وب هوک شما است و باید از HTTPS استفاده کند.

    توجه داشته باشید که Google Drive API تنها در صورتی می‌تواند اعلان‌ها را به این آدرس HTTPS ارسال کند که یک گواهی SSL معتبر روی سرور وب شما نصب شده باشد. گواهینامه های نامعتبر عبارتند از:

    • گواهی های خود امضا شده
    • گواهی امضا شده توسط یک منبع نامعتبر.
    • گواهی هایی که باطل شده اند.
    • گواهینامه هایی که موضوعی دارند که با نام میزبان هدف مطابقت ندارد.

خواص اختیاری

همچنین می توانید این فیلدهای اختیاری را با درخواست watch خود مشخص کنید:

  • یک ویژگی token که یک مقدار رشته دلخواه را برای استفاده به عنوان نشانه کانال مشخص می کند. می توانید از نشانه های کانال اطلاع رسانی برای اهداف مختلف استفاده کنید. برای مثال، می‌توانید از این رمز برای تأیید اینکه هر پیام دریافتی مربوط به کانالی است که برنامه شما ایجاد کرده است استفاده کنید - برای اطمینان از اینکه اعلان جعلی نیست - یا برای هدایت پیام به مقصد مناسب در برنامه خود بر اساس هدف این کانال حداکثر طول: 256 کاراکتر.

    این توکن در هدر HTTP X-Goog-Channel-Token در هر پیام اعلانی که برنامه شما برای این کانال دریافت می کند گنجانده شده است.

    اگر از نشانه های کانال اطلاع رسانی استفاده می کنید، توصیه می کنیم:

    • از یک قالب رمزگذاری قابل توسعه مانند پارامترهای جستجوی URL استفاده کنید. مثال: forwardTo=hr&createdBy=mobile

    • داده های حساس مانند نشانه های OAuth را درج نکنید.

  • یک رشته ویژگی expiration روی مهر زمانی یونیکس (بر حسب میلی ثانیه) از تاریخ و زمانی تنظیم شده است که می‌خواهید Google Drive API ارسال پیام برای این کانال اعلان را متوقف کند.

    اگر یک کانال دارای زمان انقضا باشد، به عنوان مقدار هدر HTTP X-Goog-Channel-Expiration (در قالب قابل خواندن توسط انسان) در هر پیام اعلانی که برنامه شما برای این کانال دریافت می کند، لحاظ می شود.

برای جزئیات بیشتر در مورد درخواست، به روش watch files و روش های changes در مرجع API مراجعه کنید.

پاسخ را تماشا کنید

اگر درخواست watch با موفقیت یک کانال اعلان ایجاد کند، یک کد وضعیت HTTP 200 OK برمی‌گرداند.

بدنه پیام پاسخ ساعت، اطلاعاتی را در مورد کانال اعلانی که ایجاد کرده اید، ارائه می دهد، همانطور که در مثال زیر نشان داده شده است.

{
  "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.
}

علاوه بر ویژگی هایی که به عنوان بخشی از درخواست خود ارسال کرده اید، اطلاعات بازگردانده شده همچنین شامل resourceId و resourceUri برای شناسایی منبعی است که در این کانال اعلان مشاهده می شود.

می‌توانید اطلاعات برگشتی را به سایر عملیات کانال اعلان ارسال کنید، مانند زمانی که می‌خواهید دریافت اعلان‌ها را متوقف کنید .

برای جزئیات بیشتر در مورد پاسخ، به روش watch files و روش های changes در مرجع API مراجعه کنید.

همگام سازی پیام

پس از ایجاد یک کانال اعلان برای تماشای یک منبع، Google Drive API یک پیام sync برای نشان دادن شروع اعلان‌ها ارسال می‌کند. مقدار هدر HTTP X-Goog-Resource-State برای این پیام ها sync است. به دلیل مشکلات زمان‌بندی شبکه، ممکن است حتی قبل از دریافت پاسخ روش watch ، پیام sync را دریافت کنید.

نادیده گرفتن اعلان sync بی خطر است، اما می توانید از آن نیز استفاده کنید. برای مثال، اگر تصمیم گرفتید که نمی‌خواهید کانال را حفظ کنید، می‌توانید از مقادیر X-Goog-Channel-ID و X-Goog-Resource-ID در یک تماس برای توقف دریافت اعلان‌ها استفاده کنید. همچنین می توانید از اعلان sync برای انجام مقداری مقداردهی اولیه برای آماده شدن برای رویدادهای بعدی استفاده کنید.

قالب پیام‌های sync Google Drive API به URL دریافتی شما در زیر نشان داده شده است.

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

پیام‌های همگام‌سازی همیشه دارای مقدار سرصفحه X-Goog-Message-Number HTTP 1 هستند. هر اعلان بعدی برای این کانال دارای یک شماره پیام است که بزرگتر از شماره قبلی است، اگرچه شماره پیام ها متوالی نخواهد بود.

کانال های اطلاع رسانی را تمدید کنید

یک کانال اعلان می‌تواند یک زمان انقضا داشته باشد، با مقداری که توسط درخواست شما یا هر محدودیت یا پیش‌فرض داخلی API Google Drive تعیین می‌شود (مقدار محدودتر استفاده می‌شود). زمان انقضای کانال، در صورت وجود، به عنوان مهر زمانی یونیکس (بر حسب میلی ثانیه) در اطلاعاتی که با روش watch بازگردانده می شود، لحاظ می شود. علاوه بر این، تاریخ و زمان انقضا (در قالب قابل خواندن توسط انسان) در هر پیام اعلانی که برنامه شما برای این کانال در هدر X-Goog-Channel-Expiration HTTP دریافت می کند گنجانده شده است.

در حال حاضر، هیچ راه خودکاری برای تمدید کانال اعلان وجود ندارد. زمانی که یک کانال به انقضای خود نزدیک است، باید با فراخوانی روش watch ، آن را با کانال جدید جایگزین کنید. مثل همیشه، باید از یک مقدار منحصر به فرد برای ویژگی id کانال جدید استفاده کنید. توجه داشته باشید که زمانی که دو کانال اعلان برای یک منبع فعال هستند، احتمالاً یک دوره زمانی "همپوشانی" وجود دارد.

اعلان ها را دریافت کنید

هر زمان که یک منبع مشاهده شده تغییر کند، برنامه شما یک پیام اعلان دریافت می کند که تغییرات را توصیف می کند. Google Drive API این پیام‌ها را به‌عنوان درخواست HTTPS POST به نشانی اینترنتی که به‌عنوان ویژگی address برای این کانال اعلان مشخص کرده‌اید ارسال می‌کند.

قالب پیام اعلان را تفسیر کنید

همه پیام‌های اعلان شامل مجموعه‌ای از هدرهای HTTP هستند که دارای پیشوندهای X-Goog- هستند. برخی از انواع اعلان‌ها می‌توانند شامل متن پیام نیز باشند.

سرصفحه ها

پیام‌های اعلان ارسال شده توسط Google Drive API به URL دریافتی شما شامل سرصفحه‌های HTTP زیر است:

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

پیام‌های اعلان برای files و changes خالی هستند.

نمونه ها

تغییر پیام اعلان برای منابع files ، که شامل بدنه درخواست نمی شود:

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

تغییر پیام اعلان برای منابع changes ، که شامل یک بدنه درخواست است: 

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"
}

به اطلاعیه ها پاسخ دهید

برای نشان دادن موفقیت، می توانید یکی از کدهای وضعیت زیر را برگردانید: 200 ، 201 ، 202 ، 204 ، یا 102 .

اگر سرویس شما از کتابخانه سرویس گیرنده API Google استفاده می‌کند و 500 ، 502 ، 503 یا 504 را برمی‌گرداند، Google Drive API با عقب‌نشینی نمایی دوباره امتحان می‌کند. هر کد وضعیت بازگشت دیگری به عنوان یک پیام ناموفق در نظر گرفته می شود.

رویدادهای اعلان Google Drive API را درک کنید

این بخش جزئیات پیام‌های اعلان‌هایی را که می‌توانید هنگام استفاده از اعلان‌های فشار با API Google Drive دریافت کنید، ارائه می‌کند.

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 در URI زیر، دریافت اعلان‌ها را برای یک کانال خاص قبل از منقضی شدن آن متوقف کنید:

https://www.googleapis.com/drive/v3/channels/stop

این روش مستلزم آن است که حداقل id کانال و ویژگی های resourceId را همانطور که در مثال زیر نشان داده شده است ارائه دهید. توجه داشته باشید که اگر Google Drive API دارای چندین نوع منبع باشد که دارای روش‌های watch هستند، تنها یک روش stop وجود دارد.

فقط کاربران با مجوز مناسب می توانند کانال را متوقف کنند. به طور خاص:

  • اگر کانال توسط یک حساب کاربری معمولی ایجاد شده باشد، فقط همان کاربر از همان مشتری (همانطور که توسط شناسه های مشتری OAuth 2.0 از نشانه های auth مشخص شده است) که کانال را ایجاد کرده است می تواند کانال را متوقف کند.
  • اگر کانال توسط یک حساب سرویس ایجاد شده باشد، هر کاربر از همان مشتری می تواند کانال را متوقف کند.

نمونه کد زیر نحوه توقف دریافت اعلان ها را نشان می دهد:

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"
}