این سند نحوه استفاده از اعلانهای فوری (push notifications) را شرح میدهد که هنگام تغییر یک منبع، به برنامه شما اطلاع میدهند.
نمای کلی
رابط برنامهنویسی نرمافزار مدیریت SDK، اعلانهای فوری (push notifications) را ارائه میدهد که به شما امکان میدهد تغییرات در منابع را رصد کنید. میتوانید از این ویژگی برای بهبود عملکرد برنامه خود استفاده کنید. این به شما امکان میدهد شبکه اضافی را حذف کنید و هزینههای مربوط به منابع نمونهبرداری (polling) را محاسبه کنید تا مشخص شود که آیا تغییر کردهاند یا خیر. هر زمان که یک منبع تحت نظارت تغییر کند، رابط برنامهنویسی نرمافزار مدیریت SDK به برنامه شما اطلاع میدهد.
برای استفاده از اعلانهای فشاری، باید دو کار انجام دهید:
آدرس اینترنتی دریافتی یا گیرندهی فراخوانی «وبهوک» خود را تنظیم کنید.
این یک سرور HTTPS است که پیامهای اعلان API را که هنگام تغییر یک منبع ایجاد میشوند، مدیریت میکند.
برای هر نقطه پایانی منبعی که میخواهید مشاهده کنید، یک ( کانال اعلان ) تنظیم کنید.
یک کانال، اطلاعات مسیریابی برای پیامهای اعلان را مشخص میکند. به عنوان بخشی از تنظیم کانال، باید URL خاصی را که میخواهید اعلانها را از آنجا دریافت کنید، مشخص کنید. هر زمان که منبع یک کانال تغییر کند، رابط برنامهنویسی نرمافزار ادمین SDK یک پیام اعلان را به عنوان درخواست
POSTبه آن URL ارسال میکند.
در حال حاضر، رابط برنامهنویسی نرمافزار مدیریت (Admin SDK API) از اعلانها برای تغییرات در منبع فعالیتها پشتیبانی میکند.
ایجاد کانالهای اعلان
برای درخواست اعلانهای فوری، باید برای هر منبعی که میخواهید نظارت کنید، یک کانال اعلان تنظیم کنید. پس از تنظیم کانالهای اعلان، رابط برنامهنویسی نرمافزار مدیریت SDK، هرگونه تغییر در منبع تحت نظارت را به برنامه شما اطلاع میدهد.
درخواستهای تماشا را انجام دهید
هر منبع API SDK Admin قابل مشاهده، یک متد watch مرتبط با خود دارد که در یک URI به شکل زیر قرار دارد:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
برای تنظیم یک کانال اعلان برای پیامهای مربوط به تغییرات در یک منبع خاص، یک درخواست POST به متد watch مربوط به آن منبع ارسال کنید.
هر کانال اعلان هم با یک کاربر خاص و هم با یک منبع خاص (یا مجموعهای از منابع) مرتبط است. درخواست watch موفقیتآمیز نخواهد بود مگر اینکه کاربر یا حساب سرویس فعلی مالک این منبع باشد یا اجازه دسترسی به آن را داشته باشد.
مثالها
تمام درخواستهای watch برای منبع Activities فرم کلی زیر را دارند:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json
{
"id": "01234567-89ab-cdef-0123456789ab",
"type": "web_hook",
"address": "https://mydomain.com/notifications",
...
"token": "target=myApp-myFilesChannelDest",
"payload": true,
"expiration": 3600
}بدنه درخواست دارای ویژگیهای زیر است:
-
id: یک UUID یا رشته منحصر به فرد مشابه که این کانال را مشخص میکند. -
type: نوع مکانیزم تحویل. مقدار این فیلد بایدweb_hookباشد. -
address: آدرس اینترنتی (URL) که اعلانها به آنجا ارسال میشوند. -
token: یک رشته دلخواه که با هر اعلان به آدرس هدف ارسال میشود، به منظور تأیید اینکه اعلان از یک منبع قابل اعتماد آمده است. -
payload: یک پرچم بولی که نشان میدهد آیا payload باید در اعلان گنجانده شود یا خیر. -
expiration: مدت زمان زنده ماندن کانال اعلان بر حسب ثانیه.
شما میتوانید از پارامترهای userKey ، applicationName ، eventName و filters برای دریافت اعلانها فقط برای رویدادها، کاربران یا برنامههای خاص استفاده کنید.
توجه: در مثالهای زیر برای وضوح بیشتر، بدنه درخواست حذف شده است.
تمام فعالیتهای مدیر را زیر نظر داشته باشید:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
مراقب همه فعالیتهای مستند باشید:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
فعالیت ادمین یک کاربر خاص را زیر نظر داشته باشید:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
مراقب یک رویداد خاص، مانند تغییر رمز عبور کاربر، باشید:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
مراقب تغییرات در یک سند خاص باشید:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef
خواص مورد نیاز
با هر درخواست watch ، باید این فیلدها را ارائه دهید:
یک رشته ویژگی
idکه به طور منحصر به فرد این کانال اعلان جدید را در پروژه شما مشخص میکند. توصیه میکنیم از یک شناسه جهانی منحصر به فرد ( UUID ) یا هر رشته منحصر به فرد مشابه استفاده کنید. حداکثر طول: ۶۴ کاراکتر.مقدار شناسهای که تنظیم کردهاید، در هدر HTTP مربوط به
X-Goog-Channel-Idهر پیام اعلانی که برای این کانال دریافت میکنید، منعکس میشود.یک رشته ویژگی
typeکه روی مقدارweb_hookتنظیم شده است.یک رشته ویژگی
addressکه روی URL تنظیم شده است که به اعلانهای این کانال اعلان گوش میدهد و به آنها پاسخ میدهد. این URL فراخوانی وبهوک شماست و باید از HTTPS استفاده کند.توجه داشته باشید که رابط برنامهنویسی نرمافزار مدیریت SDK تنها در صورتی قادر به ارسال اعلانها به این آدرس HTTPS است که یک گواهی SSL معتبر روی سرور وب شما نصب شده باشد. گواهیهای نامعتبر عبارتند از:
- گواهیهای خودامضا.
- گواهیهایی که توسط یک منبع غیرقابل اعتماد امضا شدهاند.
- گواهینامههایی که باطل شدهاند.
- گواهیهایی که موضوع آنها با نام میزبان هدف مطابقت ندارد.
خواص اختیاری
همچنین میتوانید این فیلدهای اختیاری را با درخواست watch خود مشخص کنید:
یک ویژگی
tokenکه یک مقدار رشتهای دلخواه را برای استفاده به عنوان نشانه کانال مشخص میکند. میتوانید از نشانه کانالهای اعلان برای اهداف مختلف استفاده کنید. به عنوان مثال، میتوانید از این نشانه برای تأیید اینکه هر پیام ورودی برای کانالی است که برنامه شما ایجاد کرده است - برای اطمینان از اینکه اعلان جعل نمیشود - یا برای هدایت پیام به مقصد صحیح در برنامه خود بر اساس هدف این کانال استفاده کنید. حداکثر طول: ۲۵۶ کاراکتر.این توکن در هدر HTTP مربوط به
X-Goog-Channel-Tokenدر هر پیام اعلانی که برنامه شما برای این کانال دریافت میکند، گنجانده شده است.اگر از توکنهای کانال اعلان استفاده میکنید، توصیه میکنیم:
از یک قالب کدگذاری توسعهپذیر، مانند پارامترهای پرسوجوی URL، استفاده کنید. مثال:
forwardTo=hr&createdBy=mobileدادههای حساس مانند توکنهای OAuth را وارد نکنید.
یک رشته ویژگی
expirationکه روی یک مهر زمانی یونیکس (به میلیثانیه) از تاریخ و زمانی که میخواهید رابط برنامهنویسی نرمافزار ادمین (Admin SDK API) ارسال پیام برای این کانال اعلان را متوقف کند، تنظیم شده است.اگر یک کانال زمان انقضا داشته باشد، این زمان به عنوان مقدار هدر HTTP مربوط به
X-Goog-Channel-Expiration(به فرمت قابل خواندن توسط انسان) در هر پیام اعلانی که برنامه شما برای این کانال دریافت میکند، درج میشود.
برای جزئیات بیشتر در مورد درخواست، به متد watch برای منبع Activities در مرجع API مراجعه کنید.
پاسخ را تماشا کنید
اگر درخواست watch با موفقیت یک کانال اعلان ایجاد کند، کد وضعیت HTTP 200 OK را برمیگرداند.
بدنه پیام پاسخ watch، اطلاعاتی در مورد کانال اعلانی که ایجاد کردهاید ارائه میدهد، همانطور که در مثال زیر نشان داده شده است.
{
"kind": "api#channel",
"id": "reportsApiId",
"resourceId": "o3hgv1538sdjfh",
"resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
"token": "target=myApp-myFilesChannelDest",
"expiration": 3600
} علاوه بر ویژگیهایی که به عنوان بخشی از درخواست خود ارسال کردهاید، اطلاعات برگشتی شامل resourceId و resourceUri نیز میشود تا منبعی که در این کانال اعلان در حال مشاهده است را شناسایی کند.
شما میتوانید اطلاعات برگشتی را به سایر عملیات کانال اعلان منتقل کنید، مانند زمانی که میخواهید دریافت اعلانها را متوقف کنید .
برای جزئیات بیشتر در مورد پاسخ، به متد watch برای منبع Activities در مرجع API مراجعه کنید.
پیام همگامسازی
پس از ایجاد یک کانال اعلان برای مشاهده یک منبع، رابط برنامهنویسی نرمافزار ادمین SDK یک پیام sync ارسال میکند تا نشان دهد که اعلانها در حال شروع هستند. مقدار هدر HTTP مربوط به X-Goog-Resource-State برای این پیامها، sync است. به دلیل مشکلات زمانبندی شبکه، ممکن است پیام sync حتی قبل از دریافت پاسخ متد watch دریافت شود.
نادیده گرفتن اعلان sync بیخطر است، اما میتوانید از آن نیز استفاده کنید. برای مثال، اگر تصمیم بگیرید که نمیخواهید کانال را نگه دارید، میتوانید از مقادیر X-Goog-Channel-ID و X-Goog-Resource-ID در یک فراخوانی برای توقف دریافت اعلانها استفاده کنید. همچنین میتوانید از اعلان sync برای انجام برخی تنظیمات اولیه جهت آماده شدن برای رویدادهای بعدی استفاده کنید.
قالب پیامهای sync که رابط برنامهنویسی نرمافزار مدیریت SDK به آدرس اینترنتی دریافتی شما ارسال میکند، در زیر نشان داده شده است.
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 دارند. هر اعلان بعدی برای این کانال دارای شماره پیامی است که از شماره قبلی بزرگتر است، هرچند شماره پیامها ترتیبی نخواهند بود.
کانالهای اعلان را تمدید کنید
یک کانال اعلان میتواند زمان انقضا داشته باشد، که مقداری است که یا توسط درخواست شما یا توسط هرگونه محدودیت یا پیشفرض داخلی Admin SDK API تعیین میشود (مقدار محدودتر استفاده میشود). زمان انقضای کانال، در صورت وجود، به عنوان یک مهر زمانی یونیکس (برحسب میلیثانیه) در اطلاعات برگردانده شده توسط متد watch درج میشود. علاوه بر این، تاریخ و زمان انقضا (به فرمت قابل خواندن توسط انسان) در هر پیام اعلانی که برنامه شما برای این کانال در هدر HTTP X-Goog-Channel-Expiration دریافت میکند، درج میشود.
در حال حاضر، هیچ روش خودکاری برای تمدید کانال اعلان وجود ندارد. وقتی یک کانال به انقضای خود نزدیک میشود، باید با فراخوانی متد watch آن را با یک کانال جدید جایگزین کنید. مثل همیشه، باید از یک مقدار منحصر به فرد برای ویژگی id کانال جدید استفاده کنید. توجه داشته باشید که احتمالاً زمانی که دو کانال اعلان برای یک منبع فعال هستند، یک دوره زمانی "همپوشانی" وجود دارد.
دریافت اعلانها
هر زمان که یک منبع تحت نظارت تغییر کند، برنامه شما یک پیام اعلان دریافت میکند که تغییر را شرح میدهد. رابط برنامهنویسی نرمافزار مدیریت SDK این پیامها را به عنوان درخواستهای HTTPS POST به URL که به عنوان ویژگی address برای این کانال اعلان مشخص کردهاید، ارسال میکند.
قالب پیام اعلان را تفسیر کنید
همه پیامهای اعلان شامل مجموعهای از هدرهای HTTP هستند که پیشوندهای X-Goog- دارند. برخی از انواع اعلانها همچنین میتوانند شامل یک متن پیام باشند.
سربرگها
پیامهای اعلان ارسال شده توسط رابط برنامهنویسی نرمافزار ادمین (Admin SDK API) به آدرس اینترنتی دریافتی شما شامل هدرهای HTTP زیر هستند:
| سربرگ | توضیحات |
|---|---|
| همیشه حاضر | |
| UUID یا رشته منحصر به فرد دیگری که برای شناسایی این کانال اعلان ارائه کردهاید. |
| عدد صحیحی که این پیام را برای این کانال اعلان مشخص میکند. مقدار آن برای پیامهای sync همیشه 1 است. شماره پیامها برای هر پیام بعدی در کانال افزایش مییابد، اما ترتیبی نیستند. |
| یک مقدار مبهم که منبع تحت نظارت را مشخص میکند. این شناسه در نسخههای مختلف API پایدار است. |
| وضعیت منبع جدیدی که اعلان را فعال کرده است. مقادیر ممکن: sync یا نام رویداد . |
| یک شناسه مختص به نسخه API برای منبع تحت نظر. |
| گاهی اوقات حضور دارد | |
| تاریخ و زمان انقضای کانال اعلان، بیان شده در قالب قابل خواندن توسط انسان. فقط در صورت تعریف ارائه میشود. |
| توکن کانال اعلان که توسط برنامه شما تنظیم شده است و میتوانید از آن برای تأیید منبع اعلان استفاده کنید. فقط در صورت تعریف ارائه میشود. |
پیامهای اعلان برای فعالیتها حاوی اطلاعات زیر در بدنه درخواست هستند:
| ملک | توضیحات |
|---|---|
kind | این را به عنوان یک منبع فعالیت شناسایی میکند. مقدار: رشته ثابت " admin#reports#activity ". |
id | شناسه منحصر به فرد رکورد فعالیت. |
id. time | زمان وقوع فعالیت. مقدار در قالب تاریخ و زمان ISO 8601 است. زمان، تاریخ کامل به علاوه ساعت، دقیقه و ثانیه به شکل YYYY-MM-DDThh:mm:ssTZD است. به عنوان مثال، 2010-04-05T17:30:04+01:00. |
id. uniqueQualifier | اگر چندین رویداد زمان یکسانی داشته باشند، یک توصیفگر منحصر به فرد است. |
id. applicationName | نام برنامهای که رویداد به آن تعلق دارد. مقادیر ممکن عبارتند از: |
id. customerId | شناسه منحصر به فرد برای حساب Google Workspace. |
actor | کاربری که عمل را انجام میدهد. |
actor. callerType | نوع نویسندهای که فعالیت ذکر شده در گزارش را انجام داده است. در این نسخه از API، callerType درخواست موجودیت USER یا OAuth 2LO است که عمل ذکر شده در گزارش را انجام داده است. |
actor. email | آدرس ایمیل اصلی کاربری که فعالیتهایش گزارش میشود. |
actor. profileId | شناسه منحصر به فرد پروفایل Google Workspace کاربر. |
ownerDomain | دامنه کنسول ادمین یا مالک سند برنامه Docs. این دامنهای است که تحت تأثیر رویداد گزارش قرار میگیرد. |
ipAddress | آدرس IP کاربری که عمل را انجام میدهد. این آدرس پروتکل اینترنت (IP) کاربر هنگام ورود به Google Workspace است که ممکن است موقعیت فیزیکی کاربر را نشان دهد یا ندهد. به عنوان مثال، آدرس IP میتواند آدرس سرور پروکسی کاربر یا آدرس یک شبکه خصوصی مجازی (VPN) باشد. این API از IPv4 و IPv6 پشتیبانی میکند. |
events[] | رویدادهای فعالیت در گزارش. |
events[]. type | نوع رویداد. سرویس یا ویژگی Google Workspace که یک مدیر تغییر میدهد، در ویژگی type که یک رویداد را با استفاده از ویژگی eventName شناسایی میکند، مشخص میشود. |
events[]. name | نام رویداد. این نام خاص فعالیتی است که توسط API گزارش میشود. و هر eventName مربوط به یک سرویس یا ویژگی خاص Google Workspace است که API آن را به انواع رویدادها سازماندهی میکند.برای پارامترهای درخواست eventName به طور کلی:
|
events[]. parameters[] | جفتهای مقدار پارامتر برای کاربردهای مختلف. |
events[].parameters[]. name | نام پارامتر. |
events[].parameters[]. value | مقدار رشتهای پارامتر. |
events[].parameters[]. intValue | مقدار صحیح پارامتر. |
events[].parameters[]. boolValue | مقدار بولی پارامتر. |
مثالها
پیامهای اعلان برای رویدادهای منابع فعالیت (Activity resource events) فرم کلی زیر را دارند:
POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID: ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State: eventName
X-Goog-Message-Number: 10
{
"kind": "admin#reports#activity",
"id": {
"time": datetime,
"uniqueQualifier": long,
"applicationName": string,
"customerId": string
},
"actor": {
"callerType": string,
"email": string,
"profileId": long
},
"ownerDomain": string,
"ipAddress": string,
"events": [
{
"type": string,
"name": string,
"parameters": [
{
"name": string,
"value": string,
"intValue": long,
"boolValue": boolean
}
]
}
]
}
نمونهای از رویداد فعالیت مدیر:
POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID: ret987df98743md8g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State: CREATE_USER
X-Goog-Message-Number: 23
{
"kind": "admin#reports#activity",
"id": {
"time": "2013-09-10T18:23:35.808Z",
"uniqueQualifier": "-0987654321",
"applicationName": "admin",
"customerId": "ABCD012345"
},
"actor": {
"callerType": "USER",
"email": "admin@example.com",
"profileId": "0123456789987654321"
},
"ownerDomain": "apps-reporting.example.com",
"ipAddress": "192.0.2.0",
"events": [
{
"type": "USER_SETTINGS",
"name": "CREATE_USER",
"parameters": [
{
"name": "USER_EMAIL",
"value": "liz@example.com"
}
]
}
]
}پاسخ به اعلانها
برای نشان دادن موفقیت، میتوانید هر یک از کدهای وضعیت زیر را برگردانید: 200 ، 201 ، 202 ، 204 یا 102 .
اگر سرویس شما از کتابخانه کلاینت API گوگل استفاده میکند و مقادیر 500 ، 502 ، 503 یا 504 را برمیگرداند، رابط برنامهنویسی نرمافزار مدیریت (Admin SDK API) با یک backoff نمایی (exponential backoff) دوباره تلاش میکند. هر کد وضعیت بازگشتی دیگری به عنوان یک پیام ناموفق در نظر گرفته میشود.
رویدادهای اعلان API مربوط به Admin SDK را درک کنید
این بخش جزئیاتی در مورد پیامهای اعلانی که میتوانید هنگام استفاده از اعلانهای فوری با رابط برنامهنویسی نرمافزار مدیریت SDK دریافت کنید، ارائه میدهد.
اعلانهای فشاری API گزارشها شامل دو نوع پیام هستند: پیامهای همگامسازی و اعلانهای رویداد. نوع پیام در هدر HTTP مربوط به X-Goog-Resource-State مشخص شده است. مقادیر ممکن برای اعلانهای رویداد مشابه متد activities.list است. هر برنامه رویدادهای منحصر به فردی دارد:
توقف اعلانها
ویژگی expiration زمان توقف خودکار اعلانها را کنترل میکند. میتوانید با فراخوانی متد stop در آدرس زیر، دریافت اعلانها برای یک کانال خاص را قبل از انقضای آن متوقف کنید:
https://www.googleapis.com/admin/reports_v1/channels/stop
این روش مستلزم آن است که شما حداقل id کانال و ویژگیهای resourceId را ارائه دهید، همانطور که در مثال زیر نشان داده شده است. توجه داشته باشید که اگر API Admin SDK دارای چندین نوع منبع باشد که دارای متدهای watch هستند، فقط یک متد stop وجود دارد.
فقط کاربرانی که مجوز لازم را دارند میتوانند یک کانال را متوقف کنند. به ویژه:
- اگر کانال توسط یک حساب کاربری معمولی ایجاد شده باشد، فقط همان کاربر از همان کلاینت (همانطور که توسط شناسههای کلاینت OAuth 2.0 از توکنهای احراز هویت مشخص شده است) که کانال را ایجاد کرده است، میتواند کانال را متوقف کند.
- اگر کانال توسط یک حساب کاربری سرویس ایجاد شده باشد، هر کاربری از همان کلاینت میتواند کانال را متوقف کند.
نمونه کد زیر نحوهی توقف دریافت اعلانها را نشان میدهد:
POST https://www.googleapis.com/admin/reports_v1/channels/stop
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json
{
"id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
"resourceId": "ret08u3rv24htgh289g"
}