Push Notifications, Push Notifications

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

نمای کلی

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

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

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

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

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

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

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

ایجاد کانال های اطلاع رسانی

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

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

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

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

برای راه‌اندازی یک کانال اعلان برای پیام‌های مربوط به تغییرات یک منبع خاص، یک درخواست POST به روش 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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

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

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

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

خواص اختیاری

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

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

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

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

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

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

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

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

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

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

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

سرصفحه ها

پیام‌های اعلان ارسال شده توسط Directory 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 تگ ET پیام اعلان. با ETag منبع کاربر متفاوت است.
primaryEmail آدرس ایمیل اصلی کاربر.

نمونه ها

پیام های اعلان برای رویدادهای منبع User به شکل کلی است:

POST https://mydomain.com/notifications // Your receiving URL.
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 // Your receiving URL.
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 Google استفاده می‌کند و 500 ، 502 ، 503 یا 504 را برمی‌گرداند، Directory API با عقب‌نشینی نمایی دوباره امتحان می‌کند. هر کد وضعیت بازگشت دیگری به عنوان یک پیام ناموفق در نظر گرفته می شود.

توقف اعلان ها

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

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

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

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

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

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

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