این صفحه رویدادهای گوگل درایو را که برنامه شما می‌تواند با استفاده از API رویدادهای Google Workspace در آنها مشترک شود، شرح می‌دهد. پس از اینکه تصمیم گرفتید به چه نوع رویدادهایی نیاز دارید، برای شروع دریافت رویدادها از Drive، یک اشتراک ایجاد کنید .
برای کسب اطلاعات بیشتر در مورد توسعه برنامه‌ها برای Drive، به نمای کلی API گوگل درایو مراجعه کنید.
رویدادهای پشتیبانی‌شده‌ی درایو
اشتراک‌های Google Workspace به شما امکان می‌دهند رویدادهای مربوط به انواع تغییرات زیر را در Drive دریافت کنید:
یک پیشنهاد دسترسی روی یک فایل ایجاد یا حل می‌شود.
یک نظر روی یک فایل یا فایلی در یک درایو مشترک ایجاد، ویرایش، حل، بازگشایی یا حذف می‌شود.
یک فایل عبارت است از:
- به یک پوشه یا درایو مشترک اضافه شد.
- به یک پوشه یا درایو مشترک منتقل شد.
- ویرایش شده یا نسخه جدید آپلود شده است.
- دور انداخته شده یا از سطل زباله حذف شده است.
- تغییر نام داده شده (عنوان یک فایل یا پوشه تغییر می‌کند).
یک پاسخ در یک رشته نظر در یک فایل یا فایلی در یک درایو مشترک ایجاد، ویرایش یا حذف می‌شود.
منابعی که می‌توانید برای رویدادها رصد کنید
برای دریافت رویدادها، شما یک منبع Drive را برای نظارت مشخص می‌کنید که منبع هدف اشتراک نامیده می‌شود.
رابط برنامه‌نویسی کاربردی رویدادهای فضای کاری گوگل (Google Workspace Events API) از منابع هدف زیر برای درایو پشتیبانی می‌کند:
| منبع هدف | قالب | محدودیت‌ها (در صورت وجود) |
|---|---|---|
| فایل | //drive.googleapis.com/files/ FILE که در آن FILE شناسه‌ی نام منبع | کاربری که اشتراک را تأیید می‌کند، باید مجوز دسترسی به فایل درون اشتراک را متناسب با رویداد «اشتراک در» داشته باشد. |
| درایو مشترک | //drive.googleapis.com/drives/ DRIVE که در آن DRIVE شناسه در نام منبع مربوط به منبع drives از API | این اشتراک فقط رویدادهای مربوط به موارد موجود در درایو مشترکی را دریافت می‌کند که کاربر از طریق حساب Google Workspace یا حساب Google خود در آن عضو است. |
انواع رویداد برای ایجاد اشتراک‌ها
وقتی در یک منبع Drive اشتراک ایجاد می‌کنید، از فیلد eventTypes[] برای مشخص کردن نوع رویدادهایی که می‌خواهید دریافت کنید استفاده می‌کنید. انواع رویدادها طبق مشخصات CloudEvents قالب‌بندی می‌شوند google.workspace. APPLICATION . RESOURCE . VERSION . ACTION
برای مثال، برای دریافت رویدادهای مربوط به ایجاد یک فایل در یک پوشه یا درایو مشترک، فایل را به عنوان منبع هدف و نوع رویداد را google.workspace.drive.file.v3.created تعیین می‌کنید. برای دریافت رویدادهای مربوط به ایجاد یک پیشنهاد دسترسی روی یک فایل، پیشنهاد دسترسی را به عنوان منبع هدف و نوع رویداد را google.workspace.drive.accessproposal.v3.created تعیین می‌کنید. برای کسب اطلاعات بیشتر در مورد نحوه عملکرد رویدادها، به ساختار رویدادهای Google Workspace مراجعه کنید.
جدول زیر انواع رویدادهایی را که برای اشتراک در منابع Drive پشتیبانی می‌شوند، نشان می‌دهد:
| نوع رویداد | قالب | داده‌های منابع | ||
|---|---|---|---|---|
| اشتراک در فایل‌ها و درایوهای اشتراکی | ||||
| یک پیشنهاد دسترسی روی یک فایل ایجاد می‌شود. | | | ||
| یک پیشنهاد دسترسی روی یک فایل حل و فصل می‌شود. | | | ||
| یک نظر روی یک فایل یا فایلی در یک درایو مشترک ایجاد می‌شود. | | | ||
| یک نظر روی یک فایل یا فایلی در یک درایو مشترک ویرایش می‌شود. | | | ||
| یک نظر روی یک فایل یا فایلی در یک درایو مشترک حل می‌شود. | | | ||
| یک نظر روی یک فایل یا فایلی در یک درایو مشترک دوباره باز می‌شود. | | | ||
| یک نظر روی یک فایل یا فایلی در یک درایو مشترک حذف می‌شود. | | | ||
| یک فایل به یک پوشه یا درایو مشترک اضافه می‌شود. | | | ||
| یک فایل به یک پوشه یا درایو مشترک منتقل می‌شود. | | | ||
| یک فایل ویرایش شده یا نسخه جدیدی آپلود شده است. | | | ||
| یک فایل حذف می‌شود. | | | ||
| یک فایل به سطل زباله انداخته شده است. | | | ||
| یک فایل از سطل زباله حذف می‌شود. | | | ||
| یک فایل تغییر نام داده می‌شود. | | | ||
| یک پاسخ در یک رشته نظر در یک فایل یا فایلی در یک درایو مشترک ایجاد می‌شود. | | | ||
| یک پاسخ در یک رشته نظر در یک فایل یا فایلی در یک درایو مشترک ویرایش می‌شود. | | | ||
| پاسخی که به یک رشته نظر در یک فایل یا فایلی در یک درایو مشترک داده شده، حذف می‌شود. | | | ||
داده‌های رویداد
این بخش داده‌های رویداد و نمونه‌هایی از بارهای داده برای رویدادهای موجود در Drive را شرح می‌دهد.
وقتی اشتراک Google Workspace شما رویدادی را از Drive دریافت می‌کند، فیلد data شامل اطلاعات مربوط به آن رویداد است. این اطلاعات شامل اطلاعاتی در مورد منبع Google Workspace است که تغییر کرده است. به عنوان مثال، اگر در رویدادهای فایل مشترک شده باشید، اطلاعات مربوط به این رویدادها شامل اطلاعاتی در مورد منبع files است که تغییر کرده‌اند.
داده‌های منبع در بار داده رویداد
هنگام ایجاد اشتراک، می‌توانید مشخص کنید که آیا می‌خواهید محتوای اشتراک شامل جزئیات مربوط به منبع باشد یا فقط نام منبع. به عنوان مثال، اگر می‌خواهید رویدادهایی درباره فایل‌های موجود در Drive دریافت کنید، می‌توانید مشخص کنید که می‌خواهید کدام فیلدهای یک منبع files را در محتوای رویداد دریافت کنید.
جدول زیر نمونه‌هایی از payloadهای JSON برای اشتراک در منبع Drive را ارائه می‌دهد. شناسه فایل شامل حروف، اعداد و برخی کاراکترهای خاص است که به صورت files/^[01][0-9a-zA-Z_-]+$/ ساختار یافته‌اند. برای مثال، files/1aaabbbAAABBB111222-_ . برای هر رویدادی که اشتراک دریافت می‌کند، payload در فیلد data رویداد ظاهر می‌شود:
| مثال | نوع رویداد | بار داده JSON |
|---|---|---|
کاربر یک پیشنهاد دسترسی روی یک فایل ایجاد می‌کند. | | شامل داده‌های منابع است
{
"accessProposal": [
{
"file_id": "FILE_ID",
"proposalId": "PROPOSAL_ID",
"recipientEmailAddress": "alex@altostrat.com",
"requesterEmailAddress": "kai@cymbalgroup.com",
"requestMessage": "grant me access to this file",
"rolesAndViews": [
{
"role": "writer",
"view": "published"
}
]
}
]
}
داده‌های منابع را شامل نمی‌شود
{
"accessProposal": [
{
"proposalId": "PROPOSAL_ID"
}
]
}
|
یک کاربر پیشنهاد دسترسی به یک فایل را بررسی می‌کند. | | شامل داده‌های منابع است
{
"accessProposal": [
{
"file_id": "FILE_ID",
"proposalId": "PROPOSAL_ID",
"recipientEmailAddress": "alex@altostrat.com",
"requesterEmailAddress": "kai@cymbalgroup.com",
"requestMessage": "resolve access to this file",
"rolesAndViews": [
{
"role": "writer",
"view": "published"
}
]
}
]
}
داده‌های منابع را شامل نمی‌شود
{
"accessProposal": [
{
"proposalId": "PROPOSAL_ID"
}
]
}
|
یک کاربر روی یک فایل نظر (کامنت) می‌نویسد. | | شامل داده‌های منابع است
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
داده‌های منابع را شامل نمی‌شود
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
یک کاربر نظر خود را در مورد یک فایل ویرایش می‌کند. | | شامل داده‌های منابع است
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
داده‌های منابع را شامل نمی‌شود
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
یک کاربر نظر خود را در مورد یک فایل بررسی می‌کند. | | شامل داده‌های منابع است
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
داده‌های منابع را شامل نمی‌شود
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
یک کاربر نظر خود را در مورد یک فایل دوباره باز می‌کند. | | شامل داده‌های منابع است
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
داده‌های منابع را شامل نمی‌شود
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
یک کاربر نظر خود را در مورد یک فایل حذف می‌کند. | | شامل داده‌های منابع است
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
داده‌های منابع را شامل نمی‌شود
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
کاربر فایلی را به یک پوشه یا درایو مشترک اضافه می‌کند. | | شامل داده‌های منابع است
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
داده‌های منابع را شامل نمی‌شود
{
"file": {
"id": "FILE_ID"
}
}
|
کاربر فایلی را به یک پوشه یا درایو مشترک منتقل می‌کند. | | شامل داده‌های منابع است
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
داده‌های منابع را شامل نمی‌شود
{
"file": {
"id": "FILE_ID"
}
}
|
کاربر فایلی را ویرایش می‌کند یا نسخه جدیدی از آن آپلود می‌شود. | | شامل داده‌های منابع است
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
داده‌های منابع را شامل نمی‌شود
{
"file": {
"id": "FILE_ID"
}
}
|
یک کاربر فایلی را حذف می‌کند. | | شامل داده‌های منابع است
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
داده‌های منابع را شامل نمی‌شود
{
"file": {
"id": "FILE_ID"
}
}
|
یک کاربر فایلی را حذف می‌کند. | | شامل داده‌های منابع است
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
داده‌های منابع را شامل نمی‌شود
{
"file": {
"id": "FILE_ID"
}
}
|
کاربر فایلی را از سطل زباله بازیابی می‌کند. | | شامل داده‌های منابع است
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
داده‌های منابع را شامل نمی‌شود
{
"file": {
"id": "FILE_ID"
}
}
|
یک کاربر نام یک فایل یا پوشه را تغییر می‌دهد. | | شامل داده‌های منابع است
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
داده‌های منابع را شامل نمی‌شود
{
"file": {
"id": "FILE_ID"
}
}
|
یک کاربر در یک رشته نظر، پاسخی به نظر ایجاد می‌کند. | | شامل داده‌های منابع است
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
داده‌های منابع را شامل نمی‌شود
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
یک کاربر پاسخ یک نظر را در یک رشته نظر ویرایش می‌کند. | | شامل داده‌های منابع است
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
داده‌های منابع را شامل نمی‌شود
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
یک کاربر پاسخ به یک نظر را در یک تاپیک نظر حذف می‌کند. | | شامل داده‌های منابع است
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
داده‌های منابع را شامل نمی‌شود
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
محدودیت‌ها
- وقتی فیلد بولی
includeDescendantsدرDriveOptionsبرابر باtrueباشد، اشتراک‌های Drive در درایوها و پوشه‌های مشترک همیشه یک رویداد را ارسال می‌کنند، حتی اگر فایلی که باعث ایجاد رویداد شده است، در لایه‌های زیادی پایین‌تر از پوشه‌ای که برای اشتراک Drive استفاده می‌شود، قرار گرفته باشد. - حتی اگر اشتراکی در یک پوشه ایجاد کرده باشید، ممکن است تمام رویدادهای درون سلسله مراتب فایل را دریافت نکنید زیرا ممکن است به کاربر یا برنامه اجازه دسترسی به آنها داده نشده باشد. در این حالت، اشتراک فعال باقی می‌ماند اما هیچ رویدادی برای منابعی که به آنها دسترسی ندارید، دریافت نخواهید کرد.
- اشتراک‌ها برای رویدادها در همه فایل‌ها و پوشه‌ها پشتیبانی می‌شوند، اما نه در پوشه ریشه درایوهای مشترک. اشتراک‌ها فقط برای فایل‌ها و پوشه‌های داخل درایوهای مشترک پشتیبانی می‌شوند. تغییراتی که مستقیماً در پوشه ریشه یک درایو مشترک ایجاد می‌شوند، رویدادها را فعال نمی‌کنند.
- کاربری که اشتراک را مجاز می‌کند، باید مجوز دسترسی به فایل مربوط به رویدادهایی که در آنها مشترک می‌شود را داشته باشد.
- این اشتراک فقط رویدادهایی را برای منابعی دریافت می‌کند که کاربر از طریق حساب Google Workspace یا حساب Google خود به آنها دسترسی دارد.