I componenti aggiuntivi di Google Classroom sono ora in disponibilità generale per gli sviluppatori. Per ulteriori informazioni, consulta la documentazione relativa ai componenti aggiuntivi.

Questa pagina è stata tradotta dall'API Cloud Translation.

Accedi alle API di anteprima

Questa pagina descrive come accedere alle funzionalità di anteprima dell'API Classroom e specificare le versioni di anteprima.

Le tre considerazioni da tenere presenti quando si utilizzano le funzionalità di anteprima rispetto all'API v1 stabile sono:

Il progetto Google Cloud chiamante deve essere registrato al programma di anteprima per sviluppatori di Google Workspace e aggiunto alla lista consentita da Google.
Le funzionalità API nei programmi di accesso in anteprima o di anteprima non sono esposte nelle librerie client standard e potrebbero non essere accessibili per impostazione predefinita tramite HTTP.
In un determinato momento potrebbero essere presenti più stati o versioni dell'API in anteprima.

Attivare le funzionalità di anteprima nelle librerie client

Un'opzione comune per utilizzare l'API Classroom è una libreria client. Esistono tre tipi di librerie client:

Librerie client generate dinamicamente
Librerie client statiche fornite da Google
La tua libreria client personalizzata

L'utilizzo di librerie statiche generate dinamicamente o fornite da Google è il modo consigliato per utilizzare l'API. Consulta la sezione Creare librerie client se devi creare la tua libreria. La creazione di una libreria personalizzata non rientra nell'ambito di questa guida, ma ti consigliamo di consultare la sezione Librerie dinamiche per scoprire di più sulle etichette di anteprima e sul loro ruolo in Discovery.

Librerie dinamiche

Le librerie in linguaggi come Python generano la libreria client in fase di runtime utilizzando un documento di rilevamento del servizio di rilevamento.

Un documento di scoperta è una specifica leggibile da computer per descrivere e utilizzare le API REST. Viene utilizzato per creare librerie client, plug-in IDE e altri strumenti che interagiscono con le API di Google. Un servizio potrebbe fornire più documenti di rilevamento.

I documenti di rilevamento per il servizio API Classroom (classroom.googleapis.com) sono disponibili al seguente endpoint:

https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY

La distinzione importante per l'utilizzo delle API di anteprima è la specifica del label appropriato. Per le anteprime pubbliche di Classroom, l'etichetta è DEVELOPER_PREVIEW.

Per generare la libreria Python e creare un'istanza del servizio Classroom con metodi di anteprima, puoi specificare l'URL di Discovery con il servizio, le credenziali e l'etichetta appropriati:

classroom_service_with_preview_features = googleapiclient.discovery.build(
  serviceName='classroom',
  version='v1',
  credentials=credentials,
  static_discovery=False,
  discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY)'

Per informazioni dettagliate su ogni lingua, consulta la documentazione relativa alle singole librerie client dell'API di Google.

Librerie statiche

Le librerie client in linguaggi come Java, Node.js, PHP, C# e Go devono essere create dal codice sorgente. Queste librerie vengono fornite e includono già le funzionalità di anteprima.

Per le anteprime pubbliche, le librerie client di Classroom si trovano insieme alle altre librerie client del programma Anteprima per sviluppatori di Workspace. Per le anteprime private, contatta il tuo referente Google se hai bisogno di librerie statiche generate.

Potresti dover modificare la configurazione delle dipendenze tipica per utilizzare queste librerie locali anziché importare le librerie client standard, che non dispongono delle funzionalità di anteprima.

Ad esempio, per utilizzare la libreria client Go, devi utilizzare l'istruzione replace nel file go.mod per richiedere un modulo da una directory locale:

module example.com/app

go 1.21.1

require (
    golang.org/x/oauth2 v0.12.0
    google.golang.org/api v0.139.0 // Classroom library is in here.
)

require (
  ...
)

// Use a local copy of the Go client library.
replace google.golang.org/api v0.139.0 => ../google-api-go-client

Come altro esempio, se utilizzi Node.js e npm, aggiungi il download della libreria client Node.js (googleapis-classroom-1.0.4.tgz) come dipendenza locale in package.json:

{
  "name": "nodejs-classroom-example",
  "version": "1.0.0",
  ...
  "dependencies": {
    "@google-cloud/local-auth": "^2.1.0",
    "googleapis": "^95.0.0",
    "classroom-with-preview-features": "file:./googleapis-classroom-1.0.4.tgz"
  }
}

Quindi, nella tua applicazione, richiedi il modulo classroom-with-preview-features oltre alle dipendenze regolari e crea un'istanza del servizio classroom da quel modulo:

const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithPreviewFeatures = require('classroom-with-preview-features');

...

const classroom = classroomWithPreviewFeatures.classroom({
  version: 'v1',
  auth: auth,
});

...

Specificare una versione dell'API di anteprima

Indipendentemente dal fatto che utilizzi una libreria statica o dinamica, devi specificare la versione di anteprima quando effettui chiamate API a metodi con funzionalità di anteprima.

Le diverse versioni disponibili e le funzionalità che includono sono documentate nella roadmap dell'API Classroom. La documentazione di riferimento per metodi e campi descrive anche in quali versioni è disponibile il metodo o il campo.

La specifica di una versione viene eseguita impostando il campo PreviewVersion nelle richieste. Ad esempio, per creare una rubrica con l'API di anteprima CRUD delle rubriche, devi impostare previewVersion su V1_20231110_PREVIEW nella richiesta CREATE:

rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id,
            courseWorkId=coursework_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW",
            body=body
).execute()

Le risorse associate a una chiamata al metodo di anteprima contengono anche il previewVersion utilizzato nella chiamata come campo di sola lettura, per aiutarti a capire quale versione stai utilizzando. Ad esempio, la risposta alla precedente chiamata CREATE contiene il valore V1_20231110_PREVIEW:

print(json.dumps(rubric, indent=4))
{
  "courseId": "123",
  "courseWorkId": "456",
  "creationTime": "2023-10-23T18:18:29.932Z",
  "updateTime": "2023-10-23T18:18:29.932Z",
  "id": "789",
  "criteria": [...],
  # The preview version used in the call that returned this resource.
  "previewVersion": "V1_20231110_PREVIEW",
  ...
}

Richieste HTTP

È anche possibile utilizzare l'API Classroom direttamente con HTTP.

Se effettui richieste HTTP senza una libreria client, devi comunque attivare le funzionalità di anteprima e specificare una versione di anteprima. A questo scopo, imposta un label con un'intestazione X-Goog-Visibilities e la versione di anteprima menzionata in precedenza come parametro di query o campo del corpo POST (consulta la documentazione di riferimento dell'API individuale appropriata). Per le anteprime pubbliche, l'etichetta è DEVELOPER_PREVIEW.

Ad esempio, la seguente richiesta curl esegue una chiamata LIST al servizio Rubriche con l'etichetta di visibilità e la versione di anteprima appropriate:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_ID/rubrics?key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --compressed

Puoi anche specificare la versione di anteprima nel corpo della richiesta, ad esempio quando esegui una richiesta POST:

curl --request PATCH \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]"}' \
  --compressed

L'API per ogni richiesta HTTP è descritta nella documentazione REST.

Google Apps Script

È possibile chiamare le API di anteprima da Google Apps Script. Tuttavia, esistono alcune differenze rispetto all'utilizzo tipico di Apps Script.

Devi configurare lo script in modo che utilizzi il progetto Google Cloud a cui ti sei registrato nel programma di anteprima per sviluppatori.
I servizi avanzati non supportano i metodi di anteprima, quindi devi effettuare richieste direttamente con HTTP.
Devi fornire un'etichetta e una versione di anteprima, come descritto nella sezione HTTP precedente.

Consulta la guida rapida corrispondente per acquisire familiarità con Apps Script e configurare un progetto di base. Poi segui queste istruzioni per iniziare a utilizzare le API di anteprima delle chiamate:

Modificare il progetto Cloud utilizzato dallo script

In Impostazioni progetto, fai clic su Cambia progetto e inserisci l'ID progetto Cloud del progetto a cui hai eseguito la registrazione al programma di anteprima per gli sviluppatori (per impostazione predefinita, gli script Apps Script utilizzano un progetto generico). Solo i progetti registrati possono chiamare i metodi di anteprima.

Configura le richieste HTTP

Successivamente, configura la richiesta HTTP del metodo che vuoi richiamare in Editor. Ad esempio, nella guida rapida, l'elenco dei corsi con il servizio Classroom ha il seguente aspetto:

function listCourses() {
  try {
    const response = Classroom.Courses.list();
    const courses = response.courses;
    if (!courses || courses.length === 0) {
      console.log('No courses found.');
      return;
    }
    for (const course of courses) {
      console.log('%s (%s)', course.name, course.id);
    }
  } catch (err) {
    // TODO: Developer to handle.
    console.log(err.message);
  }
}

L'operazione equivalente che utilizza direttamente HTTP è:

function listCourses() {
  const response = UrlFetchApp.fetch(
        'https://classroom.googleapis.com/v1/courses', {
        method: 'GET',
        headers: {'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()},
        contentType: 'application/json',
      });
  const data = JSON.parse(response.getContentText());
  if (data.error) {
    // TODO: Developer to handle.
    console.log(err.message);
    return;
  }
  if (!data.courses || !data.courses.length) {
    console.log('No courses found.');
    return;
  }
  for (const course of data.courses) {
    console.log('%s (%s)', course.name, course.id);
  }
}

Quando utilizzi i servizi avanzati, gli ambiti OAuth richiesti vengono dedotti, ma per effettuare chiamate HTTP dirette alle API di Google in Apps Script, devi aggiungere manualmente gli ambiti appropriati.

In Project Settings (Impostazioni progetto), attiva Show "appsscript.json" manifest file in editor (Mostra il file manifest "appsscript.json" nell'editor). Torna all'editor e aggiungi oauthScopes al file appscript.json per gli ambiti che ti servono. Gli ambiti per un determinato metodo sono elencati nella pagina di riferimento. Ad esempio, consulta la pagina del metodo di elenco courses.courseWork.rubrics.

Il file appscript.json aggiornato potrebbe avere il seguente aspetto:

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/classroom.coursework.students",
    "https://www.googleapis.com/auth/classroom.courses",
    "https://www.googleapis.com/auth/spreadsheets.readonly",
    "https://www.googleapis.com/auth/spreadsheets"
  ]
}

Fornire un'etichetta e una versione di anteprima

Nello script, assicurati di aver aggiunto l'etichetta e la versione di anteprima appropriate come descritto nella sezione HTTP precedente. La chiamata LIST di esempio al servizio Rubriche avrebbe il seguente aspetto:

function listRubrics() {
  const courseId = COURSE_ID;
  const courseWorkId = COURSE_WORK_ID;
  const response = UrlFetchApp.fetch(
         `https://classroom.googleapis.com/v1/courses/${courseId}/courseWork/${courseWorkId}/rubrics?previewVersion=V1_20231110_PREVIEW`, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer ' + ScriptApp.getOAuthToken(),
          'X-Goog-Visibilities': 'DEVELOPER_PREVIEW'
        },
        contentType: 'application/json',
        muteHttpExceptions: true
      });
  const data = JSON.parse(response.getContentText());
  console.log(data)
  if (data.error) {
    // TODO: Developer to handle.
    console.log(error.message);
    return;
  }
  if (!data.rubrics || !data.rubrics.length) {
    console.log('No rubrics for this coursework!');
    return;
  }
  console.log(data.rubrics);
}