گروه ها را مدیریت کنید

این صفحه درباره نحوه مدیریت Google Groups با Directory API است:

  • یک گروه ایجاد کنید
  • یک گروه را به روز کنید
  • یک نام مستعار گروهی اضافه کنید
  • یک گروه را بازیابی کنید
  • همه گروه ها را برای یک دامنه یا حساب بازیابی کنید
  • همه گروه ها را برای یک عضو بازیابی کنید
  • همه نام مستعار گروه را بازیابی کنید
  • نام مستعار گروه را حذف کنید
  • یک گروه را حذف کنید

یک گروه ایجاد کنید

برای ایجاد یک گروه، از درخواست POST زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را اضافه کنید. شما می توانید یک گروه برای هر دامنه مرتبط با حساب ایجاد کنید. برای رشته های پرس و جو، خواص درخواست و پاسخ، به روش groups.insert مراجعه کنید.

POST https://admin.googleapis.com/admin/directory/v1/groups

درخواست JSON زیر یک بدنه درخواست نمونه را نشان می دهد که یک گروه ایجاد می کند. آدرس ایمیل گروه sales_group@example.com است:

{
   "email": "sales_group@example.com",
   "name": "Sales Group",
   "description": "This is the Sales group."
}

یک پاسخ موفق یک کد وضعیت HTTP 201 و ویژگی های گروه جدید را برمی گرداند.

یک گروه را به روز کنید

برای به‌روزرسانی تنظیمات یک گروه، از درخواست PUT زیر استفاده کنید و مجوز توضیح داده شده در درخواست‌های مجاز را اضافه کنید. groupKey آدرس ایمیل گروه، هر یک از آدرس ایمیل نام مستعار گروه یا id منحصر به فرد گروه است. برای رشته های پرس و جو، خواص درخواست و پاسخ، به روش groups.update مراجعه کنید.

PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey

به طور کلی، گوگل توصیه می کند از آدرس ایمیل گروه به عنوان کلیدی برای داده های پایدار استفاده نکنید زیرا آدرس ایمیل ممکن است تغییر کند.

در مثال زیر، groupKey یکتا nnn و نام گروه APAC Sales Group است: 

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn

{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

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

یک پاسخ موفق یک کد وضعیت HTTP 201 و ویژگی های گروه جدید را برمی گرداند: 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

یک نام مستعار گروهی اضافه کنید

برای افزودن نام مستعار گروهی، از درخواست POST زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را اضافه کنید. groupKey آدرس ایمیل گروه، هر یک از آدرس ایمیل نام مستعار گروه یا id منحصر به فرد گروه است. برای رشته های پرس و جو، خواص درخواست و پاسخ، به منبع groups مراجعه کنید.

POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

به طور کلی، گوگل توصیه می کند از آدرس ایمیل گروه به عنوان کلیدی برای داده های پایدار استفاده نکنید زیرا آدرس ایمیل ممکن است تغییر کند.

درخواست JSON زیر یک درخواست نمونه برای ایجاد نام مستعار یک گروه را نشان می دهد. groupKey id منحصر به فرد گروه است که توسط NNNN نشان داده شده است 

POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases

{
    "alias": "best_sales_group@example.com"
}

یک پاسخ موفق یک کد وضعیت HTTP 201 و ویژگی های نام مستعار گروه جدید را برمی گرداند.

یک گروه را بازیابی کنید

برای بازیابی یک گروه، از درخواست GET زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را اضافه کنید. groupKey آدرس ایمیل گروه، هر یک از آدرس ایمیل نام مستعار گروه یا id منحصر به فرد گروه است. برای رشته های پرس و جو، خواص درخواست و پاسخ، به متد groups.get مراجعه کنید.
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey

به طور کلی، گوگل توصیه می کند از آدرس ایمیل گروه به عنوان کلیدی برای داده های دائمی استفاده نکنید زیرا آدرس ایمیل ممکن است تغییر کند.

در مثال زیر، شناسه groupKey یکتا nnnn است:

GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn

یک پاسخ موفق یک کد وضعیت HTTP 200 و تنظیمات گروه را برمی‌گرداند:

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

همه گروه ها را برای یک دامنه یا حساب بازیابی کنید

برای بازیابی همه گروه‌ها برای یک دامنه یا حساب خاص، از درخواست GET زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را اضافه کنید. برای رشته های پرس و جو، خواص درخواست و پاسخ، به روش groups.list مراجعه کنید. برای خوانایی، این مثال از بازگشت خط استفاده می کند:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name
&customer=my_customer or customerId&pageToken=pagination token
&maxResults=max results

هنگام بازیابی همه گروه ها برای یک دامنه یا حساب، موارد زیر را در نظر بگیرید:

  • همه گروه ها برای یک زیر دامنه: از آرگومان domain با نام دامنه استفاده کنید.
  • همه گروه‌ها برای حساب: از آرگومان customer با مقدار my_customer یا customerId حساب استفاده کنید. به عنوان مدیر حساب، از رشته my_customer برای نشان دادن customerId حساب خود استفاده کنید. اگر فروشنده ای هستید که به حساب مشتری فروخته شده دسترسی دارد، از customerId حساب فروش مجدد استفاده کنید. برای مقدار customerId از نام دامنه اصلی حساب در درخواست بازیابی همه کاربران در عملیات دامنه استفاده کنید. پاسخ به دست آمده دارای مقدار customerId است.
  • استفاده از آرگومان های domain و customer : Directory API همه گروه ها را برای domain برمی گرداند.
  • عدم استفاده از آرگومان های domain و customer : Directory API همه گروه های حساب مرتبط با my_customer را برمی گرداند. این حساب customerId مدیر درخواست کننده است.
  • استفاده از هر دو آرگومان customer و userKey : Directory API یک خطا را برمی‌گرداند. شما باید دو درخواست جداگانه با این آرگومان ها ارائه دهید.

در مثال زیر، یک مدیر حساب از my_customer برای درخواست فهرستی از گروه‌های یک حساب استفاده می‌کند:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2

در مثال زیر، درخواست مدیر فروشنده همه گروه‌ها را برای حساب فروش مجدد با customerId C03az79cb برمی‌گرداند. حداکثر نتایج بازگشتی در هر صفحه پاسخ 2 است. یک nextPageToken برای لیست بعدی کاربران در این پاسخ وجود دارد:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2

یک پاسخ موفق ، کد وضعیت HTTP 200 و گروه ها را به ترتیب حروف الفبا ایمیل گروه برمی گرداند: 

{
"kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support@sales.com",
      "name": "Sales support",
      "directMembersCount": "6",
      "description": "The sales support group",
      "adminCreated": true
     },
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "travel@sales.com",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "best_sales_group@example.com"
       }
      ],
      "nonEditableAliases: [
       {
         "alias": "liz@test.com"
       }
      ]
     },
  "nextPageToken": "NNNN"
  }

همه گروه ها را برای یک عضو بازیابی کنید

برای بازیابی همه گروه‌هایی که عضوی برای آنها اشتراک دارد، از درخواست GET زیر استفاده کنید و مجوز توضیح داده شده در درخواست‌های مجوز را اضافه کنید. برای خوانایی، این مثال از بازگشت خط استفاده می کند:

GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=user key
?pageToken=pagination token
&maxResults=maximum results per response page
  • یک عضو می تواند کاربر یا گروه باشد.
  • userKey می تواند آدرس ایمیل اصلی کاربر، آدرس ایمیل نام مستعار کاربر، آدرس ایمیل اصلی یک گروه، نام مستعار ایمیل یک گروه یا id منحصر به فرد کاربر باشد که با استفاده از عملیات بازیابی کاربر قابل یافتن است.
  • کاربر یا گروه مشخص شده در userKey باید متعلق به دامنه شما باشد.
  • از رشته پرس و جو pageToken برای پاسخ هایی با تعداد زیادی گروه استفاده کنید. در مورد صفحه بندی، پاسخ ویژگی nextPageToken را برمی گرداند که یک نشانه برای صفحه بعدی نتایج پاسخ می دهد. درخواست بعدی شما از این نشانه به عنوان مقدار رشته پرس و جو pageToken استفاده می کند.
  • استفاده از هر دو آرگومان customer و userKey : Directory API یک خطا را برمی‌گرداند. شما باید دو درخواست جداگانه با این آرگومان ها ارائه دهید.

برای خواص درخواست و پاسخ، به روش groups.list مراجعه کنید.

یک پاسخ موفق یک کد وضعیت HTTP 200 و لیست اطلاعات اعضا را برمی گرداند:

  • همه گروه هایی که عضوی برای آنها اشتراک دارد، از جمله گروه های خارج از دامنه کاربر، برگردانده می شوند.
  • گروه ها به ترتیب حروف الفبا آدرس ایمیل هر گروه بازگردانده می شوند.
  • در متن پاسخ، id شناسه منحصر به فرد گروه است.
  • در پاسخ، فهرست کردن یک گروه از خارج از دامنه کاربر، شامل نام مستعار گروه خارجی نیست. 
{
    "kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "sales_group@example.com",
      "name": "sale group",
      "directMembersCount": "5",
      "description": "Sales group"
     },
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support_group.com",
      "name": "support group",
      "directMembersCount": "5",
      "description": "Support group"
     }
  ],
   "nextPakeToken": "NNNNN"
}

همه نام مستعار گروه را بازیابی کنید

برای بازیابی همه نام‌های مستعار یک گروه، از درخواست GET زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را اضافه کنید. groupKey می تواند آدرس ایمیل اصلی گروه، id منحصر به فرد گروه یا هر یک از ایمیل های نام مستعار گروه باشد. برای ویژگی‌های درخواست و پاسخ، به منبع groups مراجعه کنید.

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

یک پاسخ موفق یک کد وضعیت HTTP 201 و لیستی از نام های مستعار گروه را برمی گرداند.

نام مستعار گروه را حذف کنید

برای حذف نام مستعار یک گروه، از درخواست DELETE زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را اضافه کنید. groupKey می تواند آدرس ایمیل اصلی گروه، id منحصر به فرد گروه یا هر یک از ایمیل های نام مستعار گروه باشد. aliasId نام مستعار در حال حذف است. برای ویژگی های درخواست و پاسخ، به منبع groups مراجعه کنید:

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId

یک پاسخ موفق یک کد وضعیت HTTP 201 را برمی گرداند.

یک گروه را حذف کنید

برای حذف یک گروه، از درخواست DELETE زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را اضافه کنید. groupKey id منحصر به فرد گروه است:

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
به عنوان مثال، این درخواست DELETE گروهی را که دارای id گروه nnnn است حذف می کند:
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn

یک پاسخ موفق یک کد وضعیت HTTP 200 را برمی گرداند.

هنگامی که یک گروه حذف می شود، موارد زیر رخ می دهد:

  • همه اعضای گروه حذف می شوند. حساب‌های کاربری اعضا حذف نمی‌شوند.
  • آرشیو گروه حذف می شود.
  • پیام های ارسال شده به آدرس گروه حذف شده تحویل داده نمی شود. در عوض، فرستنده یک پیام برگشتی دریافت می کند.