Enterprise License Manager API: Developer's Guide

این سند توضیح می‌دهد که چگونه مدیران در سطح حساب و فروشنده می‌توانند از Enterprise License Manager API برای مدیریت تخصیص مجوز کاربران استفاده کنند. هنگامی که مجوزهای SKU محصول حساب شما فعال شد و کاربران شما ایجاد شدند، از Enterprise License Manager API برای اختصاص، به روز رسانی، بازیابی و حذف مجوزها برای کاربران حساب خود استفاده کنید.

در این نسخه، Enterprise License Manager API توسط مدیران حساب و فروشنده استفاده می شود. مدیران تفویض شده با امتیاز License Management می‌توانند از API مدیریت مجوز سازمانی نیز استفاده کنند.

توجه: Enterprise License Manager API توسط یک مشتری Google استفاده می شود. برای کسب اطلاعات در مورد نحوه مدیریت مجوزها توسط برنامه‌نویسان برنامه‌های شخص ثالث Google، به Google Workspace Marketplace API مراجعه کنید.

Enterprise License Manager API بر اساس رویکرد طراحی Representational State Transfer (RESTful) به خدمات وب است.

مدیریت مجوزها

مجوز اختصاص دهید

قبل از این عملیات، مشتری یا فروشنده مجوزهای محصول Google را سفارش داده و کاربر را ایجاد کرده است. برای اختصاص یکی از این مجوزهای محصول به این کاربر، از درخواست POST HTTP زیر استفاده کنید. هدر Authorization را همانطور که در درخواست‌های مجاز توضیح داده شده است اضافه کنید. برای شناسه‌های محصول و SKU، محصولات و SKUهای موجود API را ببینید:

POST https://www.googleapis.com/apps/licensing/v1/product/productId/sku/skuId/user

توجه: به کاربر می‌توان مجوزهایی برای طیف وسیعی از محصولات مختلف Google اختصاص داد. اما به یک کاربر در هر بار فقط یک مجوز SKU به هر محصول اختصاص داده می شود. با استفاده از API، مجوز SKU کاربر را می توان به مجوز SKU دیگری در محصول اختصاص داد.

این مثال Google-Drive-storage-20GB SKU را به کاربری که آدرس ایمیل اصلی او alex@example.com است اختصاص می دهد:

POST https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-20GB/user

بدنه درخواست JSON:

{
  "userId" : "alex@example.com",
}

یک پاسخ موفق یک کد وضعیت HTTP 200 را برمی گرداند. برای کدهای خطای احتمالی، به کدهای خطای API مراجعه کنید. در صورت موفقیت آمیز بودن، پاسخ وضعیت تخصیص مجوز را در قالب داده JSON برمی گرداند.

پاسخ JSON

{
  "kind": "licensing#licenseAssignment",
  "etags": "etag value",
  "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-20GB/user/alex@example.com",
  "userId": "alex@example.com",
  "productId": "Google-Drive-storage",
  "skuId": "Google-Drive-storage-20GB",
  "skuName": "Google Drive storage 20 GB",
  "productName": "Google Drive storage"
}

برای اطلاعات بیشتر، به صفحه مرجع روش درج LicenseAssignments مراجعه کنید.

SKU محصول کاربر را با SKU متفاوت در همان محصول تخصیص دهید

برای تخصیص مجدد مجوز کاربر به مجوز جدید SKU در همان محصول، از درخواست PUT HTTP زیر استفاده کنید. API از دستور پچ نیز پشتیبانی می کند. هدر Authorization را همانطور که در درخواست‌های مجاز توضیح داده شده است اضافه کنید. برای شناسه‌های محصول و SKU، محصولات و SKUهای موجود API را ببینید:

PUT https://www.googleapis.com/apps/licensing/v1/product/productId/sku/the current skuId/user/user's email

این مثال SKU Google-Drive-storage-20GB فعلی را با Google-Drive-storage-50GB به روز می کند. SKU مجوز فعلی در URI درخواست و SKU مجوز جدید در بدنه درخواست است:

PUT https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-20GB/user/alex@example.com

بدنه درخواست JSON دارای موارد زیر است:

{
  "kind": "licensing#licenseAssignment",
  "etags": "etag value",
  "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com",
  "userId": "alex@example.com",
  "productId": "Google-Drive-storage",
  "skuId": "Google-Drive-storage-50GB",
  "skuName": "Google Drive storage 50 GB",
  "productName": "Google Drive storage"
}

یک پاسخ موفق یک کد وضعیت HTTP 200 را برمی گرداند. برای کدهای خطای احتمالی، به کدهای خطای API مراجعه کنید. در صورت موفقیت آمیز بودن، پاسخ وضعیت تخصیص مجوز را در قالب داده JSON برمی گرداند.

پاسخ JSON

{
  "kind": "licensing#licenseAssignment",
  "etags": "etag value",
  "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com",
  "userId": "alex@example.com",
  "productId": "Google-Drive-storage",
  "skuId": "Google-Drive-storage-50GB",
  "skuName": "Google Drive storage 50 GB",
  "productName": "Google Drive storage"
}

برای اطلاعات بیشتر، به صفحات مرجع روش به روز رسانی LicenseAssignments و روش وصله مراجعه کنید.

تمام مجوزهای اختصاص داده شده به کاربران برای یک محصول خاص را بازیابی کنید

برای دریافت تمام مجوزهای کاربر برای یک محصول خاص، از درخواست GET HTTP زیر استفاده کنید. هدر Authorization را همانطور که در درخواست‌های مجاز توضیح داده شده است اضافه کنید. رشته query customerId نام دامنه اصلی مشتری است. رشته پرس و جو maxResults تعیین می کند که چه تعداد ورودی مجوز کاربر در پاسخ API برگردانده می شود:

GET https://www.googleapis.com/apps/licensing/v1/product/productId/users?customerId=primary domain name&maxResults=max results per page

برای شناسه‌های محصول و SKU، محصولات و SKUهای موجود API را ببینید.

این مثال صفحه اول نتایج را برای همه کاربران در دامنه example.com که مجوزهای اختصاص داده شده برای محصول ذخیره‌سازی Google-Drive را نشان می‌دهد، فهرست می‌کند:

GET https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/users?customerId=example.com&maxResults=2

یک پاسخ موفق یک کد وضعیت HTTP 200 را برمی گرداند. برای کدهای خطای احتمالی، به کدهای خطای API مراجعه کنید. در صورت موفقیت آمیز بودن، پاسخ لیست مجوز را در قالب JSON برمی گرداند.

پاسخ JSON

{
  "kind" : "licensing#licenseAssignmentList",
  "etag": "etag value",
  "nextPageToken" : "the next page token value",
  "items": [
  {
    "kind": "licensing#licenseAssignment",
    "etags": "etag value",
    "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com",
    "userId": "alex@example.com",
    "productId": "Google-Drive-storage",
    "skuId": "Google-Drive-storage-50GB",
    "skuName": "Google Drive storage 50 GB",
    "productName": "Google Drive storage"
  },
  {
    "kind": "licensing#licenseAssignment",
    "etags": "etag value",
    "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-200GB/user/keshav@example.com",
    "userId": "keshav@example.com",
    "productId": "Google-Drive-storage",
    "skuId": "Google-Drive-storage-200GB",
    "skuName": "Google Drive storage 200 GB",
    "productName": "Google Drive storage"
  },
  ...
}

برای اطلاعات بیشتر، به صفحه مرجع روش LicenseAssignments listForProduct مراجعه کنید.

همه مجوزهای اختصاص داده شده به کاربران برای SKU محصول خاص را بازیابی کنید

برای دریافت لیستی از همه کاربران دارای مجوز برای SKU محصول خاص، از درخواست GET HTTP زیر استفاده کنید. هدر Authorization را همانطور که در درخواست‌های مجاز توضیح داده شده است اضافه کنید. رشته query customerId نام دامنه اصلی مشتری است. رشته پرس و جو maxResults تعیین می کند که چه تعداد ورودی کاربر در پاسخ API برگردانده می شود:

GET https://www.googleapis.com/apps/licensing/v1/product/productId/sku/skuId/users?customerId=primary domain name&maxResults=max results per response page

برای شناسه‌های محصول و SKU، به محصولات و SKUهای موجود API مراجعه کنید

این مثال صفحه اول همه کاربران در دامنه example.com را که مجوزی برای Google-Drive-storage-200GB SKU اختصاص داده اند، برمی گرداند. پاسخ، دو ورودی کاربر را در هر صفحه فهرست می‌کند:

GET https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-200GB/users?customerId=example.com&maxResults=2

یک پاسخ موفق یک کد وضعیت HTTP 200 را برمی گرداند. برای کدهای خطای احتمالی، به کدهای خطای API مراجعه کنید. در صورت موفقیت آمیز بودن، پاسخ لیست مجوزها را در قالب JSON برمی گرداند.

پاسخ JSON

{
  "kind" : "licensing#licenseAssignmentList",
   "etag": "etag value",
   "nextPageToken" : "next page token's value",
   "items": [
    {
     "kind": "licensing#licenseAssignment",
     "etags": "etag value",
     "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-200GB/user/alex@example.com",
     "userId": "alex@example.com",
     "productId": "Google-Drive-storage",
     "skuId": "Google-Drive-storage-200GB",
     "skuName": "Google Drive storage 200 GB",
     "productName": "Google Drive storage"
    },
    {
     "kind": "licensing#licenseAssignment",
     "etags": "etag value",
     "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-200GB/user/mary@example.com",
     "userId": "mary@example.com",
     "productId": "Google-Drive-storage",
     "skuId": "Google-Drive-storage-200GB",
     "skuName": "Google Drive storage 200 GB",
     "productName": "Google Drive storage"
    },
    ...
  }

برای اطلاعات بیشتر، به صفحه مرجع روش LicenseAssignments listForProductAndSku مراجعه کنید.

مجوز یک کاربر خاص را بر اساس SKU محصول بازیابی کنید

برای دریافت مجوز یک کاربر خاص توسط SKU محصول، از درخواست GET HTTP زیر استفاده کنید. هدر Authorization را همانطور که در درخواست‌های مجاز توضیح داده شده است اضافه کنید. برای شناسه‌های محصول و SKU، محصولات و SKUهای موجود API را ببینید:

GET https://www.googleapis.com/apps/licensing/v1/product/productId/sku/skuId/user/userId

این مثال SKU محصول 50 گیگابایتی ذخیره سازی Google Drive را برای کاربری که userId آن alex@example.com است دریافت می کند:

GET https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com

اگر کاربر این مجوز را داشته باشد، یک پاسخ موفق و کد وضعیت HTTP 200 است. برای کدهای خطای احتمالی، به کدهای خطای API مراجعه کنید. در صورت موفقیت آمیز بودن، پاسخ مجوز کاربر را در قالب JSON برمی گرداند.

پاسخ JSON

{
  "kind": "licensing#licenseAssignment",
  "etag": "etag value",
  "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com",
  "userId": "keshav@example.com",
  "productId": "Google-Drive-storage",
  "skuId": "Google-Drive-storage-50GB",
  "skuName": "Google Drive storage 50 GB",
  "productName": "Google Drive storage"
}

برای اطلاعات بیشتر، به صفحه مرجع دریافت روش LicenseAssignments مراجعه کنید.

یک مجوز را حذف کنید

برای لغو اختصاص مجوز از یک کاربر، از درخواست DELETE HTTP زیر استفاده کنید. هدر Authorization را همانطور که در درخواست‌های مجاز توضیح داده شده است اضافه کنید. برای شناسه‌های محصول و SKU، محصولات و SKUهای موجود API را ببینید:

DELETE https://www.googleapis.com/apps/licensing/v1/product/productId/sku/skuId/user/userId

این مثال مجوز Google-Drive-storage-50GB به کاربری که userId آن alex@example.com است، واگذار نشده است:

DELETE https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com

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

برای اطلاعات بیشتر، به صفحه مرجع روش حذف LicenseAssignments مراجعه کنید.

کدهای خطا

اگر درخواست ناموفق باشد، پاسخ توضیح مختصری از خطا دارد:

کد خطا شرح
400 درخواست بد - ایمیل کاربر معتبر نیست.
400 درخواست بد - SKU/محصول وجود ندارد.
401 Actor اعتباری برای فراخوانی این API ندارد.
404 اگر کاربر این مجوز را نداشته باشد، پاسخ دارای کد خطای «نیافت نشد» است.
412 پیش شرطی برآورده نشده است. برای جزئیات بیشتر در مورد این خطا، قسمت message را بررسی کنید. مثلا:
  • Auto License switching is not allowed.
  • Auto License un-assignment is not allowed.
  • For reassign operations, the new SKU should be different from the old SKU: sku
  • Reassign operation can't be performed on different products: product1, product2
  • Reassign operation can't be performed on different users: user1, user2
  • There aren't enough available licenses for the specified product-SKU pair
  • User already has a license for the specified product and SKU
  • User already has a license of the product, but with a different SKU. To reassign a new SKU for this product, use the 'update' operation.
503 سرویس مدیر مجوز در دسترس نیست.