Push Notifications, Push Notifications

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

نمای کلی

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

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

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

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

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

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

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

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

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

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

هر منبع API دایرکتوری قابل مشاهده، یک متد watch مرتبط در یک URI به شکل زیر دارد:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

برای تنظیم یک کانال اعلان برای پیام‌های مربوط به تغییرات در یک منبع خاص، یک درخواست POST به متد watch مربوط به آن منبع ارسال کنید.

هر کانال اعلان هم با یک کاربر خاص و هم با یک منبع خاص (یا مجموعه‌ای از منابع) مرتبط است. درخواست watch موفقیت‌آمیز نخواهد بود مگر اینکه کاربر یا حساب سرویس فعلی مالک این منبع باشد یا اجازه دسترسی به آن را داشته باشد.

مثال‌ها

تمام درخواست‌های watch برای منبع User برای یک دامنه واحد، فرم کلی زیر را دارند:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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",
  "params": {
    "ttl": 3600
  }
}

در بدنه درخواست، id کانال، type web_hook و آدرس اینترنتی دریافتی خود را در address وارد کنید. همچنین می‌توانید به صورت اختیاری موارد زیر را نیز وارد کنید:

  • یک token برای استفاده به عنوان توکن کانال شما.
  • یک ttl در params برای درخواست زمان ماندگاری (time-to-live) برای این کانال بر حسب ثانیه.

از پارامترهای domain و event برای مشخص کردن دامنه و نوع رویدادی که می‌خواهید برای آن اعلان دریافت کنید، استفاده کنید.

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

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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",
  "params": {
    "ttl": 3600
  }
}

از پارامترهای customer و event برای مشخص کردن شناسه منحصر به فرد حساب گوگل مشتری و نوع رویدادی که می‌خواهید برای آن اعلان دریافت کنید، استفاده کنید.

مقادیر ممکن برای event عبارتند از:

  • add : رویداد ایجاد شده توسط کاربر
  • delete : رویداد حذف کاربر
  • makeAdmin : رویداد تغییر وضعیت کاربر ادمین
  • undelete : رویداد بازگردانی اطلاعات حذف شده توسط کاربر
  • update : رویداد به‌روزرسانی‌شده توسط کاربر

توجه: در مثال‌های زیر برای وضوح بیشتر، بدنه درخواست حذف شده است.

به رویدادهای ایجاد شده توسط کاربر برای دامنه mydomain.com توجه کنید:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

به رویدادهای ایجاد شده توسط کاربر برای customer my_customer توجه کنید:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

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

با هر درخواست 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 برای منبع Users در مرجع API مراجعه کنید.

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

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4",
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1384823632000
}

بدنه پاسخ جزئیات کانال مانند موارد زیر را ارائه می‌دهد:

  • id : شناسه‌ای که برای این کانال مشخص کرده‌اید.
  • resourceId : شناسه منبع تحت نظر.
  • resourceUri : شناسه‌ی مختص به نسخه از منبعِ تحتِ نظر.
  • token : توکنی که در بدنه درخواست ارائه شده است.
  • expiration : زمان انقضای کانال به صورت یک مهر زمانی یونیکس بر حسب میلی‌ثانیه.

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

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

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

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

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

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

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

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

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

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

سربرگ‌ها

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

سربرگ توضیحات
همیشه حاضر
X-Goog-Channel-ID UUID یا رشته منحصر به فرد دیگری که برای شناسایی این کانال اعلان ارائه کرده‌اید.
X-Goog-Message-Number عدد صحیحی که این پیام را برای این کانال اعلان مشخص می‌کند. مقدار آن برای پیام‌های sync همیشه 1 است. شماره پیام‌ها برای هر پیام بعدی در کانال افزایش می‌یابد، اما ترتیبی نیستند.
X-Goog-Resource-ID یک مقدار مبهم که منبع تحت نظارت را مشخص می‌کند. این شناسه در نسخه‌های مختلف API پایدار است.
X-Goog-Resource-State وضعیت منبع جدیدی که اعلان را فعال کرده است. مقادیر ممکن: sync یا نام رویداد .
X-Goog-Resource-URI یک شناسه مختص به نسخه API برای منبع تحت نظر.
گاهی اوقات حضور دارد
X-Goog-Channel-Expiration تاریخ و زمان انقضای کانال اعلان، بیان شده در قالب قابل خواندن توسط انسان. فقط در صورت تعریف ارائه می‌شود.
X-Goog-Channel-Token توکن کانال اعلان که توسط برنامه شما تنظیم شده است و می‌توانید از آن برای تأیید منبع اعلان استفاده کنید. فقط در صورت تعریف ارائه می‌شود.

پیام‌های اعلان برای کاربران حاوی اطلاعات زیر در بدنه درخواست هستند:

ملک توضیحات
kind این را به عنوان یک منبع کاربر شناسایی می‌کند. مقدار: رشته ثابت " admin#directory#user ".
id شناسه منحصر به فرد منبع کاربر.
etag ETag پیام اعلان. متفاوت از ETag منبع کاربر.
primaryEmail آدرس ایمیل اصلی کاربر.

مثال‌ها

پیام‌های اعلان برای رویدادهای منابع User فرم کلی زیر را دارند:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
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/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

مثالی از رویداد حذف کاربر:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

پاسخ به اعلان‌ها

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

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

توقف اعلان‌ها

ویژگی expiration زمان توقف خودکار اعلان‌ها را کنترل می‌کند. می‌توانید با فراخوانی متد stop در آدرس زیر، دریافت اعلان‌ها برای یک کانال خاص را قبل از انقضای آن متوقف کنید: 

https://www.googleapis.com/admin/directory_v1/channels/stop

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

فقط کاربرانی که مجوز لازم را دارند می‌توانند یک کانال را متوقف کنند. به ویژه:

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

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

POST https://www.googleapis.com/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}