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

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

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

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

تستند واجهة برمجة تطبيقات إدارة تراخيص Enterprise إلى منهج تصميم النقل العام التمثيلي (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",
}

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

للمزيد من المعلومات، يُرجى الاطّلاع على الصفحة المرجعية إدراج طريقة "مهام الترخيص".

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

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

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

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

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

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

استرداد جميع المستخدمين الذين حصلوا على تراخيص لمنتج معين

للحصول على جميع تراخيص المستخدمين لمنتج معيّن، استخدِم طلب 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-storage:

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 في "المهام الدراسية".

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

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

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 الخاصة بالمهام.

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

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

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

يحصل هذا المثال على رمز تخزين تعريفي للمنتج في مساحة تخزين Google Drive بسعة 50 غيغابايت للمستخدم الذي يكون 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"
}

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

حذف ترخيص

لإلغاء تعيين ترخيص من مستخدم، استخدِم طلب 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. للتعرّف على رموز الخطأ المحتملة، يُرجى الاطّلاع على رموز الخطأ لواجهة برمجة التطبيقات.

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

رموز الخطأ

إذا لم يتم قبول الطلب، سيتضمّن الردّ تفسيرًا مختصرًا للخطأ:

رمز الخطأ الوصف
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 خدمة إدارة التراخيص غير متوفرة.