Enterprise License Manager API: מדריך למפתחים

במסמך הזה מוסבר איך אדמינים ברמת החשבון ואדמינים של מפיצים יכולים להשתמש ב-Enterprise License Manager API כדי לנהל הקצאות של רישיונות משתמשים. אחרי שרישיונות המק"טים של המוצרים בחשבון יופעלו והמשתמשים שלך ייווצרו, אפשר להשתמש ב-Enterprise License Manager API כדי להקצות, לעדכן, לאחזר ולמחוק רישיונות למשתמשים בחשבון.

בגרסה הזו, אדמינים של חשבונות ומפיצים משתמשים ב-Enterprise License Manager API. אדמינים מואצלים עם הרשאת 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 כפי שמתואר בקטע הרשאות בקשות. למידע על מזהי מוצרים ומק"טים, מומלץ לעיין ברשימת המוצרים והמק"טים הזמינים של ה-API: 

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

הערה: אפשר להקצות למשתמש רישיונות למגוון רחב של מוצרי Google שונים. עם זאת, בכל רגע נתון מוקצה למשתמש רק רישיון מק"ט אחד לכל מוצר. באמצעות ה-API, ניתן להקצות מחדש את רישיון המק"ט של משתמש לרישיון מק"ט אחר בתוך המוצר.

בדוגמה הזו, המק"ט של 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. קודי שגיאה אפשריים מפורטים בקודי השגיאה של ה-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"
}

למידע נוסף, אפשר לעיין בדף העזר בנושא insert method של LicenseAssignments.

הקצאה מחדש של מק"ט של מוצר של משתמש באמצעות מק"ט אחר באותו מוצר

כדי להקצות מחדש רישיון של משתמש למק"ט חדש של רישיון באותו מוצר, יש להשתמש בבקשת ה-HTTP הבאה PUT. ה-API תומך גם בתחביר התיקונים. יש לכלול את הכותרת Authorization כפי שמתואר בקטע הרשאות בקשות. למידע על מזהי מוצרים ומק"טים, מומלץ לעיין ברשימת המוצרים והמק"טים הזמינים של ה-API: 

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. המק"ט הנוכחי של הרישיון נמצא ב-URI של הבקשה, והמק"ט החדש של הרישיון נמצא בגוף הבקשה: 

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.

אחזור של כל הרישיונות שהוקצו למשתמשים למוצר ספציפי

כדי לקבל את כל רישיונות המשתמשים של מוצר ספציפי, צריך להשתמש בבקשת ה-HTTP הבאה GET. יש לכלול את הכותרת Authorization כפי שמתואר בקטע הרשאות בקשות. מחרוזת השאילתה customerId היא השם של הדומיין הראשי של הלקוח. מחרוזת השאילתה maxResults קובעת כמה רשומות של רישיונות משתמשים יוחזרו בתגובה של ה-API:

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

למידע על מזהי מוצרים ומק"טים, אפשר לעיין בקטע מוצרים ומק"טים שזמינים ב-API.

בדוגמה הבאה מוצג הדף הראשון של תוצאות לכל המשתמשים בדומיין 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. קודי שגיאה אפשריים מפורטים בקודי השגיאה של ה-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"
  },
  ...
}

מידע נוסף זמין בדף העזר של listForProduct method ב-License לידs.

אחזור כל הרישיונות שהוקצו למשתמשים במק"ט של מוצר ספציפי

כדי לקבל רשימה של כל המשתמשים שיש להם רישיונות למק"ט של מוצר ספציפי, צריך להשתמש בבקשת ה-HTTP הבאה GET. יש לכלול את הכותרת Authorization כפי שמתואר בקטע הרשאות בקשות. מחרוזת השאילתה 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

מזהי מוצרים ומק"טים מפורטים במאמר מוצרים ומק"טים שזמינים ב-API

בדוגמה הזו מוצג הדף הראשון מתוך כל המשתמשים בדומיין 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. קודי שגיאה אפשריים מפורטים בקודי השגיאה של ה-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"
    },
    ...
  }

מידע נוסף זמין בדף העזר של listForProductAndSku אצל LicenseAssignments.

אחזור רישיון של משתמש ספציפי לפי מק"ט של מוצר

כדי לקבל רישיון של משתמש ספציפי לפי מק"ט של מוצר, צריך להשתמש בבקשת ה-HTTP הבאה GET. יש לכלול את הכותרת Authorization כפי שמתואר בקטע הרשאות בקשות. למידע על מזהי מוצרים ומק"טים, מומלץ לעיין ברשימת המוצרים והמק"טים הזמינים של ה-API:

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

בדוגמה הבאה מתקבל מק"ט המוצר לאחסון ב-Google Drive בנפח 50GB עבור המשתמש ש-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.

מחיקת רישיון

כדי לבטל הקצאת רישיון למשתמש, יש להשתמש בבקשת ה-HTTP הבאה: DELETE. יש לכלול את הכותרת Authorization כפי שמתואר בקטע הרשאות בקשות. למידע על מזהי מוצרים ומק"טים, מומלץ לעיין ברשימת המוצרים והמק"טים הזמינים של ה-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 בקשה שגויה – המק"ט/המוצר לא קיים.
401 למשתמש אין פרטי כניסה כדי לקרוא ל-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 השירות 'מנהל הרישיונות' לא זמין.