این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

اعلان های فشاری

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

بررسی اجمالی

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

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

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

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

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

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

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

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

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

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

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

مثال ها

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

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "payload": true, // (Optional) Whether to include the payload (message body) in notifications.
  "expiration": 3600 // (Optional) Your requested channel expiration time.
}

می‌توانید از پارامترهای 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 ) یا هر رشته منحصر به فرد مشابهی استفاده کنید. حداکثر طول: 64 کاراکتر.
مقدار شناسه ای که تنظیم کرده اید در سرصفحه HTTP X-Goog-Channel-Id هر پیام اعلانی که برای این کانال دریافت می کنید بازتاب می یابد.
یک type رشته ویژگی با مقدار web_hook تنظیم شده است.
یک رشته ویژگی address روی URL تنظیم شده است که به اعلان‌های این کانال اعلان گوش می‌دهد و به آن پاسخ می‌دهد. این URL پاسخ به تماس وب هوک شما است و باید از HTTPS استفاده کند.
توجه داشته باشید که Admin SDK API فقط در صورتی می‌تواند اعلان‌ها را به این آدرس HTTPS ارسال کند که یک گواهی SSL معتبر روی سرور وب شما نصب شده باشد. گواهینامه های نامعتبر عبارتند از:
- گواهی های خود امضا شده
- گواهی امضا شده توسط یک منبع نامعتبر.
- گواهی هایی که باطل شده اند.
- گواهینامه هایی که موضوعی دارند که با نام میزبان هدف مطابقت ندارد.

خواص اختیاری

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

یک ویژگی token که یک مقدار رشته دلخواه را برای استفاده به عنوان نشانه کانال مشخص می کند. می توانید از نشانه های کانال اطلاع رسانی برای اهداف مختلف استفاده کنید. به عنوان مثال، می‌توانید از این رمز برای تأیید اینکه هر پیام دریافتی مربوط به کانالی است که برنامه شما ایجاد کرده است استفاده کنید - برای اطمینان از اینکه اعلان جعلی نیست - یا برای هدایت پیام به مقصد مناسب در برنامه خود بر اساس هدف این کانال حداکثر طول: 256 کاراکتر.
این توکن در هدر HTTP X-Goog-Channel-Token در هر پیام اعلانی که برنامه شما برای این کانال دریافت می کند گنجانده شده است.
اگر از نشانه های کانال اطلاع رسانی استفاده می کنید، توصیه می کنیم:
- از یک قالب رمزگذاری قابل توسعه مانند پارامترهای جستجوی URL استفاده کنید. مثال: forwardTo=hr&createdBy=mobile
- داده های حساس مانند نشانه های OAuth را درج نکنید.
توجه: اگر باید داده های بسیار حساس را ارسال کنید، قبل از افزودن آن به توکن مطمئن شوید که رمزگذاری شده است.
یک رشته ویژگی expiration روی مهر زمانی یونیکس (بر حسب میلی ثانیه) از تاریخ و زمانی تنظیم شده است که می‌خواهید Admin SDK API ارسال پیام برای این کانال اعلان را متوقف کند.
اگر یک کانال دارای زمان انقضا باشد، به عنوان مقدار هدر HTTP X-Goog-Channel-Expiration (در قالب قابل خواندن توسط انسان) در هر پیام اعلانی که برنامه شما برای این کانال دریافت می کند، لحاظ می شود.

توجه: برای Admin SDK API، حداکثر زمان انقضا 21600 ثانیه است. اگر ویژگی expiration را در درخواست خود تنظیم نکنید، زمان انقضا به طور پیش فرض روی 21600 ثانیه پس از زمان فعلی تنظیم می شود.

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

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

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

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

{
  "kind": "api#channel",
  "id": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

توجه: ویژگی resourceId یک شناسه پایدار و مستقل از نسخه برای منبع است. ویژگی resourceUri URI متعارف منبع تماشا شده در متن نسخه API فعلی است، بنابراین مختص نسخه است.

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

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

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

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

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

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

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

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

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

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

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

توجه: درخواست‌های HTTPS تحویل اعلان، یک نماینده کاربر APIs-Google را مشخص می‌کند و به دستورالعمل‌های robots.txt احترام می‌گذارد، همانطور که در APIs Google User Agent توضیح داده شده است.

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

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

سرصفحه ها

پیام‌های اعلان ارسال شده توسط Admin SDK 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`	این را به عنوان یک منبع Activity شناسایی می کند. مقدار: رشته ثابت " `admin#reports#activity` ".
`id`	شناسه منحصر به فرد سابقه فعالیت.
`id. time`	زمان وقوع فعالیت. مقدار در قالب تاریخ و زمان ISO 8601 است. زمان تاریخ کامل به اضافه ساعت، دقیقه و ثانیه به شکل YYYY-MM-DDThh:mm:ssTZD است. به عنوان مثال، 2010-04-05T17:30:04+01:00.
`id. uniqueQualifier`	واجد شرایط منحصر به فرد اگر چندین رویداد زمان یکسان داشته باشند.
`id. applicationName`	نام برنامه ای که رویداد به آن تعلق دارد. مقادیر ممکن عبارتند از: مدیر تقویم راندن گروه ها group_enterprise وارد شدن سیار سمل نشانه user_accounts
`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` به طور کلی: اگر `eventName` داده نشود، گزارش تمام نمونه‌های ممکن `eventName` را برمی‌گرداند. وقتی یک `eventName` درخواست می‌کنید، پاسخ API همه فعالیت‌هایی را که حاوی آن `eventName` هستند برمی‌گرداند. این امکان وجود دارد که فعالیت های برگشتی علاوه بر مورد درخواستی دارای ویژگی های `eventName` دیگری نیز باشند.
`events[]. parameters[]`	جفت مقدار پارامتر برای برنامه های مختلف.
`events[].parameters[]. name`	نام پارامتر.
`events[].parameters[]. value`	مقدار رشته پارامتر
`events[].parameters[]. intValue`	مقدار صحیح پارامتر
`events[].parameters[]. boolValue`	مقدار بولی پارامتر.

مثال ها

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

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

رویدادهای اعلان Admin SDK API را درک کنید

این بخش جزئیات پیام‌های اعلان‌هایی را که می‌توانید هنگام استفاده از اعلان‌های فشار با Admin SDK API دریافت کنید، ارائه می‌کند.

گزارش‌ها اعلان‌های فشاری API شامل دو نوع پیام هستند: پیام‌های همگام‌سازی و اعلان‌های رویداد. نوع پیام در هدر X-Goog-Resource-State HTTP نشان داده شده است. مقادیر ممکن برای اعلان‌های رویداد مانند روش activities.list است. هر برنامه دارای رویدادهای منحصر به فردی است:

توقف اعلان ها

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

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

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

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

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

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

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