API Enterprise License Manager: guida per gli sviluppatori

Questo documento descrive come gli amministratori a livello di account e rivenditori possono utilizzare l'API Enterprise License Manager per gestire l'assegnazione delle licenze agli utenti. Dopo aver abilitato le licenze SKU del prodotto per il tuo account e aver creato gli utenti, utilizza l'API Enterprise License Manager per assegnare, aggiornare, recuperare ed eliminare le licenze per gli utenti del tuo account.

In questa versione, l'API Enterprise License Manager viene utilizzata dagli amministratori di account e rivenditori. Gli amministratori delegati con il privilegio License Management possono anche utilizzare l'API Enterprise License Manager.

Nota: l'API Enterprise License Manager è utilizzata da un cliente Google. Per informazioni su come gli sviluppatori di applicazioni di terze parti di Google gestiscono le licenze, consulta l'articolo sull'API Google Workspace Marketplace.

L'API Enterprise License Manager si basa sull'approccio di progettazione Representational State Transfer (RESTful) ai servizi web.

Gestione delle licenze

Assegna una licenza

Prima di questa operazione, il cliente o il rivenditore ha ordinato le licenze dei prodotti Google e ha creato l'utente. Per assegnare una di queste licenze di prodotto all'utente, utilizza la seguente richiesta HTTP POST. Includi l'intestazione Authorization come descritto in Autorizzazione delle richieste. Per gli ID prodotto e SKU, consulta i Prodotti e SKU disponibili dell'API: 

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

Nota:è possibile assegnare a un utente le licenze per una vasta gamma di prodotti Google diversi. Tuttavia, a un utente viene assegnata una sola licenza SKU per prodotto alla volta. Utilizzando l'API, la licenza SKU di un utente può essere riassegnata a una licenza SKU diversa all'interno del prodotto.

In questo esempio viene assegnato lo SKU Google-Drive-storage-20 GB all'utente il cui indirizzo email principale è alex@example.com: 

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

Corpo della richiesta JSON: 

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

Una risposta corretta restituisce un codice di stato HTTP 200. Per conoscere i possibili codici di errore, consulta la sezione Codici di errore dell'API. Se l'esito è positivo, la risposta restituisce lo stato di assegnazione delle licenze in formato di dati JSON.

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

Per ulteriori informazioni, consulta la pagina di riferimento del insert method di LicenseAssignments.

Riassegna lo SKU del prodotto di un utente con uno SKU diverso nello stesso prodotto

Per riassegnare la licenza di un utente a un nuovo SKU di licenza all'interno dello stesso prodotto, utilizza la seguente richiesta HTTP PUT. L'API supporta anche la sintassi della patch. Includi l'intestazione Authorization come descritto in Autorizzazione delle richieste. Per gli ID prodotto e SKU, consulta i Prodotti e SKU disponibili dell'API: 

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

Questo esempio aggiorna l'attuale SKU Google-Drive-storage-20 GB con Google-Drive-storage-50 GB. L'attuale SKU della licenza si trova nell'URI della richiesta, mentre il nuovo SKU della licenza si trova nel corpo della richiesta: 

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

Il corpo della richiesta JSON contiene :

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

Una risposta corretta restituisce un codice di stato HTTP 200. Per conoscere i possibili codici di errore, consulta la sezione Codici di errore dell'API. Se l'esito è positivo, la risposta restituisce lo stato di assegnazione della licenza in formato di dati JSON.

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

Per maggiori informazioni, consulta le pagine di riferimento relative al metodo di aggiornamento LicenseAssignments e al metodo patch.

Recuperare tutti gli utenti a cui sono state assegnate licenze per un prodotto specifico

Per ottenere tutte le licenze utente per un prodotto specifico, utilizza la seguente richiesta HTTP GET. Includi l'intestazione Authorization come descritto in Autorizzazione delle richieste. La stringa di query customerId è il nome di dominio principale del cliente. La stringa di query maxResults determina il numero di voci relative alla licenza utente che vengono restituite nella risposta dell'API:

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

Per gli ID prodotto e SKU, consulta i Prodotti e SKU disponibili dell'API.

In questo esempio viene elencata la prima pagina dei risultati di tutti gli utenti del dominio example.com a cui sono state assegnate licenze per il prodotto Google-Drive-storage:

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

Una risposta corretta restituisce un codice di stato HTTP 200. Per conoscere i possibili codici di errore, consulta la sezione Codici di errore dell'API. Se l'esito è positivo, la risposta restituisce l'elenco di licenze in formato JSON.

Risposta 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"
  },
  ...
}

Per ulteriori informazioni, consulta la pagina di riferimento del metodo listForProduct di LicenseAssignments.

Recuperare tutti gli utenti a cui sono state assegnate le licenze per uno specifico SKU di prodotto

Per ottenere un elenco di tutti gli utenti con licenze per uno SKU di prodotto specifico, utilizza la seguente richiesta HTTP GET. Includi l'intestazione Authorization come descritto in Autorizzazione delle richieste. La stringa di query customerId è il nome di dominio principale del cliente. La stringa di query maxResults determina il numero di voci utente restituite nella risposta dell'API:

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

Per gli ID prodotto e SKU, consulta i Prodotti e SKU disponibili dell'API.

Questo esempio restituisce la prima pagina di tutti gli utenti del dominio example.com a cui è stata assegnata una licenza per lo SKU Google-Drive-storage-200 GB. La risposta elenca due voci utente per pagina:

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

Una risposta corretta restituisce un codice di stato HTTP 200. Per conoscere i possibili codici di errore, consulta la sezione Codici di errore dell'API. Se l'esito è positivo, la risposta restituisce l'elenco di licenze in formato JSON.

Risposta 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"
    },
    ...
  }

Per ulteriori informazioni, consulta la pagina di riferimento del metodo listForProductAndSku di LicenseAssignments.

Recuperare la licenza di un utente specifico in base allo SKU del prodotto

Per ottenere la licenza di un utente specifico in base allo SKU di prodotto, utilizza la seguente richiesta HTTP GET. Includi l'intestazione Authorization come descritto in Autorizzazione delle richieste. Per gli ID prodotto e SKU, consulta i Prodotti e SKU disponibili dell'API:

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

In questo esempio viene recuperato lo SKU del prodotto da 50 GB per lo spazio di archiviazione di Google Drive per l'utente il cui 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

Se l'utente dispone di questa licenza, si tratta di una risposta riuscita e di un codice di stato HTTP 200. Per conoscere i possibili codici di errore, consulta la sezione Codici di errore dell'API. Se l'esito è positivo, la risposta restituisce la licenza dell'utente in formato JSON.

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

Per ulteriori informazioni, consulta la pagina di riferimento get method di LicenseAssignments.

Eliminare una licenza

Per annullare l'assegnazione di una licenza a un utente, utilizza la seguente richiesta HTTP DELETE. Includi l'intestazione Authorization come descritto in Autorizzazione delle richieste. Per gli ID prodotto e SKU, consulta i Prodotti e SKU disponibili dell'API:

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

In questo esempio, l'assegnazione della licenza Google-Drive-storage-50 GB viene annullata per l'utente il cui 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

Una risposta corretta restituisce un codice di stato HTTP 200. Per conoscere i possibili codici di errore, consulta la sezione Codici di errore dell'API.

Per ulteriori informazioni, consulta la pagina di riferimento del metodo di eliminazione di LicenseAssignments.

Codici di errore

Se la richiesta non va a buon fine, la risposta contiene una breve spiegazione dell'errore:

Codice di errore Descrizione
400 Richiesta errata: indirizzo email utente non valido.
400 Richiesta errata: SKU/prodotto inesistente.
401 L'attore non dispone delle credenziali per chiamare questa API.
404 Se l'utente non dispone di questa licenza, la risposta contiene il codice di errore "non trovato".
412 Una condizione preliminare non è stata soddisfatta. Per maggiori dettagli su questo errore, controlla il campo message. Ad esempio:
  • 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 Il servizio License Manager non è disponibile.