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

این سند نحوه استفاده از اعلان‌های فوری (push notifications) را شرح می‌دهد که هنگام تغییر یک منبع، به برنامه شما اطلاع می‌دهند.

نمای کلی

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

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

  • آدرس اینترنتی دریافتی یا گیرنده‌ی فراخوانی «وب‌هوک» خود را تنظیم کنید.

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

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

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

در حال حاضر، API گوگل درایو از اعلان‌ها برای تغییرات در files و متدهای changes پشتیبانی می‌کند.

ایجاد کانال‌های اعلان

برای درخواست اعلان‌های فوری، باید برای هر منبعی که می‌خواهید نظارت کنید، یک کانال اعلان تنظیم کنید. پس از تنظیم کانال‌های اعلان، API گوگل درایو هنگام تغییر هر منبع تحت نظارت، به برنامه شما اطلاع می‌دهد.

درخواست‌های تماشا را انجام دهید

هر منبع 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 ) یا هر رشته منحصر به فرد مشابه استفاده کنید. حداکثر طول: ۶۴ کاراکتر.

    مقدار شناسه‌ای که تنظیم کرده‌اید، در هدر HTTP مربوط به X-Goog-Channel-Id هر پیام اعلانی که برای این کانال دریافت می‌کنید، منعکس می‌شود.

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

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

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

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

خواص اختیاری

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

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

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

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

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

    • داده‌های حساس مانند توکن‌های OAuth را وارد نکنید.

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

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

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

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

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

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

{
  "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 مراجعه کنید.

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

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

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

قالب پیام‌های sync که 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 دارند. هر اعلان بعدی برای این کانال دارای شماره پیامی است که از شماره قبلی بزرگتر است، هرچند شماره پیام‌ها ترتیبی نخواهند بود.

کانال‌های اعلان را تمدید کنید

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

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

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

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

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

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

سربرگ‌ها

پیام‌های اعلان ارسال شده توسط API گوگل درایو به آدرس اینترنتی دریافتی شما شامل هدرهای 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 ، 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 و 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 گوگل استفاده می‌کند و مقادیر 500 ، 502 ، 503 یا 504 را برمی‌گرداند، API گوگل درایو با یک backoff نمایی دوباره تلاش می‌کند. هر کد وضعیت بازگشتی دیگری به عنوان یک پیام ناموفق در نظر گرفته می‌شود.

رویدادهای اعلان API گوگل درایو را درک کنید

این بخش جزئیاتی در مورد پیام‌های اعلانی که می‌توانید هنگام استفاده از اعلان‌های فوری با 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 را ارائه دهید، همانطور که در مثال زیر نشان داده شده است. توجه داشته باشید که اگر 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"
}