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

این صفحه نحوه مدیریت گروه‌های گوگل با استفاده از 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 : API دایرکتوری تمام گروه‌های مربوط به domain را برمی‌گرداند.
  • عدم استفاده از آرگومان‌های domain و customer : API دایرکتوری تمام گروه‌های مربوط به حساب مرتبط با my_customer را برمی‌گرداند. این همان customerId حساب کاربری مدیری است که درخواست را انجام می‌دهد.
  • استفاده از هر دو آرگومان customer و userKey : API دایرکتوری خطا برمی‌گرداند. شما باید دو درخواست جداگانه با این آرگومان‌ها ارسال کنید.

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

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

در مثال زیر، درخواست مدیر نمایندگی فروش، تمام گروه‌های مربوط به حساب کاربری فروخته شده با customerId C03az79cb را برمی‌گرداند. حداکثر نتایج برگردانده شده در هر صفحه پاسخ، ۲ است. یک 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 منحصر به فرد کاربر باشد که می‌توان آن را با استفاده از عملیات بازیابی کاربر (Retrieve a user) پیدا کرد.
  • کاربر یا گروهی که در userKey مشخص شده است باید متعلق به دامنه شما باشد.
  • برای پاسخ‌هایی با تعداد زیادی گروه، از رشته‌ی پرس‌وجوی pageToken استفاده کنید. در صورت صفحه‌بندی، پاسخ، ویژگی nextPageToken را برمی‌گرداند که یک توکن برای صفحه‌ی بعدی نتایج پاسخ ارائه می‌دهد. درخواست بعدی شما از این توکن به عنوان مقدار رشته‌ی پرس‌وجوی pageToken استفاده می‌کند.
  • استفاده از هر دو آرگومان customer و userKey : 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"
     }
  ],
   "nextPageToken": "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 زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های Authorize را نیز وارد کنید. 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 را برمی‌گرداند.

وقتی گروهی حذف می‌شود، موارد زیر اتفاق می‌افتد:

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