واجهة برمجة تطبيقات إدارة تراخيص Enterprise: دليل مطوّري البرامج

يوضّح هذا المستند كيفية استخدام مشرفي مستوى الحساب والمورّدين لواجهة برمجة التطبيقات Enterprise License Manager API لإدارة عمليات منح التراخيص للمستخدمين. بعد تفعيل تراخيص رموز التخزين التعريفية للمنتجات في حسابك وإنشاء المستخدمين، استخدِم واجهة برمجة التطبيقات Enterprise License Manager API لمنح التراخيص لمستخدمي حسابك وتعديلها واستردادها وحذفها.

في هذا الإصدار، يتم استخدام واجهة برمجة تطبيقات إدارة تراخيص Enterprise من قِبل مشرفي الحساب والموردين. يمكن أيضًا للمشرفين المفوَّضين الذين لديهم امتياز License Management استخدام واجهة برمجة التطبيقات Enterprise License Manager API.

ملاحظة: يستخدم عميل Google واجهة برمجة التطبيقات Enterprise License Manager API. للحصول على معلومات عن كيفية إدارة مطوّري التطبيقات التابعين لجهات خارجية في Google للتراخيص، يُرجى الاطّلاع على Google Workspace Marketplace API.

تستند واجهة برمجة التطبيقات Enterprise License Manager API إلى نهج تصميم Representational State Transfer (RESTful) لخدمات الويب.

إدارة التراخيص

منح ترخيص

قبل هذه العملية، طلب العميل أو المورِّد تراخيص منتجات Google وأنشأ المستخدم. لمنح أحد تراخيص المنتج هذه لهذا المستخدم، استخدِم طلب HTTP التالي من POST. أدرِج العنوان Authorization كما هو موضّح في تفويض الطلبات. بالنسبة إلى معرّفات المنتجات ورموز التخزين التعريفية، يمكنك الاطّلاع على المنتجات ورموز التخزين التعريفية المتاحة في واجهة برمجة التطبيقات: 

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

ملاحظة: يمكن منح المستخدم تراخيص لمجموعة كبيرة من منتجات Google المختلفة. ولكن يتم تخصيص ترخيص واحد فقط لرمز التخزين التعريفي لكل منتج للمستخدم في كل مرة. باستخدام واجهة برمجة التطبيقات، يمكن إعادة تعيين ترخيص رمز التخزين التعريفي للمستخدم إلى ترخيص رمز تخزين تعريفي مختلف داخل المنتج.

يحدِّد هذا المثال رمز التخزين Google-Drive-storage-20GB للمستخدم الذي يكون عنوان بريده الإلكتروني الأساسي هو 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",
}

يعرض الاستجابة الناجحة 200 رمز حالة HTTP. للحصول على رموز الخطأ المحتملة، يمكنك الاطّلاع على رموز الخطأ في واجهة برمجة التطبيقات. في حال نجاحها، ستعرض الاستجابة حالة تعيين الترخيص بتنسيق بيانات 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.

إعادة تخصيص رمز التخزين التعريفي لمنتج مستخدم برمز تخزين تعريفي مختلف في المنتج نفسه

لإعادة منح ترخيص مستخدم إلى رمز تخزين تعريفي جديد للترخيص ضمن المنتج نفسه، استخدِم طلب PUT HTTP التالي. تتيح واجهة برمجة التطبيقات أيضًا بنية الإصلاح. أدرِج العنوان Authorization كما هو موضّح في تفويض الطلبات. للحصول على أرقام تعريف المنتجات ورموز التخزين التعريفية، اطّلِع على المنتجات ورموز التخزين التعريفية المتاحة في واجهة برمجة التطبيقات: 

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

يعدّل هذا المثال رمز التخزين التعريفي الحالي Google-Drive-storage-20GB باستخدام رمز التخزين التعريفي Google-Drive-storage-50GB. يتوفّر رمز التخزين التعريفي الحالي للترخيص في عنوان URL للطلب، ويتوفّر رمز التخزين التعريفي الجديد للترخيص في نص الطلب: 

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

يعرض الاستجابة الناجحة 200 رمز حالة HTTP. لمعرفة رموز الخطأ المحتمَلة، يُرجى الاطّلاع على رموز الخطأ لواجهة برمجة التطبيقات. في حال نجاح العملية، تعرض الاستجابة حالة تعيين الترخيص بتنسيق بيانات 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.

استرداد جميع المستخدمين الذين تم تعيين تراخيص لمنتج معين لهم

للحصول على جميع تراخيص المستخدمين لمنتج معيّن، استخدِم طلب HTTP التالي GET. أدرِج العنوان Authorization كما هو موضّح في تفويض الطلبات. سلسلة طلب البحث customerId هي اسم النطاق الأساسي للعميل. تحدِّد سلسلة طلب البحث maxResults عدد إدخالات ترخيص المستخدم التي يتم عرضها في ردّ واجهة برمجة التطبيقات:

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

بالنسبة إلى معرّفات المنتجات ورموز التخزين التعريفية، يمكنك الاطّلاع على المنتجات ورموز التخزين التعريفية المتاحة في واجهة برمجة التطبيقات.

يسرد هذا المثال الصفحة الأولى من النتائج لجميع المستخدمين في نطاق example.com الذين تم منحهم تراخيص لمنتج مساحة التخزين في Google Drive:

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

عند الاستجابة الناجحة، يتم عرض رمز حالة HTTP 200. للحصول على رموز الخطأ المحتملة، يمكنك الاطّلاع على رموز الخطأ في واجهة برمجة التطبيقات. في حال نجاح العملية، يعرض الردّ قائمة التراخيص بتنسيق 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"
  },
  ...
}

لمزيد من المعلومات، يُرجى الاطّلاع على صفحة مرجعية لطريقة listForProduct في licenseAssignments.

استرداد جميع التراخيص التي تم منحها للمستخدمين لرمز تخزين تعريفي لمنتج معيّن

للحصول على قائمة بجميع المستخدمين الذين لديهم تراخيص لرموز تخزين تعريفية لمنتج معيّن، استخدِم طلب HTTP التالي GET. أدرِج العنوان Authorization كما هو موضّح في تفويض الطلبات. سلسلة طلب البحث customerId هي اسم النطاق الأساسي للعميل. تحدِّد سلسلة طلب البحث maxResults عدد إدخالات المستخدمين التي يتم عرضها في استجابة واجهة برمجة التطبيقات:

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

بالنسبة إلى معرّفات المنتجات ورموز التخزين التعريفية، يمكنك الاطّلاع على المنتجات ورموز التخزين التعريفية المتاحة في واجهة برمجة التطبيقات.

يعرض هذا المثال الصفحة الأولى من جميع المستخدمين في نطاق example.com الذين تم منحهم ترخيصًا لرمز التخزين التعريفي لـ Google-Drive-storage-200GB. تسرد الاستجابة إدخالين للمستخدم لكل صفحة:

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. لمعرفة رموز الخطأ المحتمَلة، يُرجى الاطّلاع على رموز الخطأ لواجهة برمجة التطبيقات. في حال نجاح العملية، يعرض الردّ قائمة التراخيص بتنسيق 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"
    },
    ...
  }

لمزيد من المعلومات، يُرجى الاطّلاع على صفحة مرجعية لطريقة listForProductAndSku في licenseAssignments.

استرداد ترخيص مستخدم معيّن حسب رمز التخزين التعريفي للمنتج

للحصول على ترخيص مستخدم معيّن حسب رمز التخزين التعريفي للمنتج، استخدِم طلب HTTP GET التالي. أدرِج العنوان Authorization كما هو موضّح في تفويض الطلبات. بالنسبة إلى معرّفات المنتجات ورموز التخزين التعريفية، يمكنك الاطّلاع على المنتجات ورموز التخزين التعريفية المتاحة في واجهة برمجة التطبيقات:

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

يحصل هذا المثال على رمز التخزين التعريفي لمنتج بسعة 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. للحصول على رموز الخطأ المحتملة، يمكنك الاطّلاع على رموز الخطأ في واجهة برمجة التطبيقات. في حال نجاح العملية، يعرض الردّ ترخيص المستخدم بتنسيق 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.

حذف ترخيص

لإلغاء تعيين ترخيص من مستخدم، استخدِم طلب HTTP DELETE التالي. ضمِّن العنوان Authorization كما هو موضّح في الموافقة على الطلبات. للحصول على أرقام تعريف المنتجات ورموز التخزين التعريفية، اطّلِع على المنتجات ورموز التخزين التعريفية المتاحة في واجهة برمجة التطبيقات:

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. لمعرفة رموز الخطأ المحتمَلة، يُرجى الاطّلاع على رموز الخطأ لواجهة برمجة التطبيقات.

لمزيد من المعلومات، يُرجى الاطّلاع على صفحة مرجعية لطريقة حذف licenseAssignments.

رموز الخطأ

إذا لم ينجح الطلب، فيحتوي الرد على شرح موجز للخطأ:

رمز الخطأ الوصف
400 طلب غير صالح: البريد الإلكتروني للمستخدم غير صالح.
400 طلب غير صالح: رمز التخزين التعريفي أو المنتج غير متوفّر.
401 لا يملك الفاعل بيانات اعتماد للاتصال بواجهة برمجة التطبيقات هذه.
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 خدمة "إدارة التراخيص" غير متاحة.