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 inserito nella lista consentita da Google.
Le funzionalità dell'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 saperne 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 esecuzione 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 scoperta.

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

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

La distinzione importante per lavorare con le API di anteprima è specificare il valore 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 linguaggio, consulta la documentazione della libreria client delle singole API di Google.

Librerie statiche

Le librerie client in linguaggi come Java, Node.js, PHP, C# e Go devono essere compilate dall'origine. Queste librerie sono fornite e le funzionalità di anteprima sono già incorporate.

Per le anteprime pubbliche, le librerie client di Classroom sono disponibili insieme alle altre librerie client del Programma Anteprima per sviluppatori di Workspace. Per le anteprime private, rivolgiti al tuo contatto Google se hai bisogno di generare librerie statiche.

Potresti dover modificare la configurazione delle dipendenze standard 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 la direttiva 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"
  }
}

Poi, 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,
});

...

Specifica una versione dell'API di anteprima

Indipendentemente dall'utilizzo di 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à incluse sono descritte nella roadmap dell'API Classroom. La documentazione di riferimento per i metodi e i campi descrive anche le versioni in cui il metodo o il campo è disponibile.

Per specificare una versione, imposta il campo PreviewVersion nelle richieste. Ad esempio, per creare una rubrica con l'API di anteprima CRUD Rubrics, 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 valore previewVersion utilizzato nella chiamata come campo di sola lettura, per aiutarti a capire quale versione stai utilizzando. Ad esempio, la risposta della chiamata CREATE precedente 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 invii richieste HTTP senza una libreria client, devi comunque attivare le funzionalità di anteprima e specificare una versione di anteprima. A tal fine, imposta un label con un'intestazione X-Goog-Visibilities e la versione di anteprima sopra menzionata come parametro di query o campo del corpo POST (consulta la documentazione di riferimento dell'API singola appropriata). Per le anteprime pubbliche, l'etichetta è DEVELOPER_PREVIEW.

Ad esempio, la seguente richiesta curl effettua una chiamata LIST al servizio Rubrics 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 effettui 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 da utilizzare il progetto Google Cloud per cui hai eseguito la registrazione al programma di anteprima per sviluppatori.
I servizi avanzati non supportano i metodi di anteprima, pertanto dovrai effettuare le richieste direttamente con HTTP.
Devi fornire un'etichetta e una versione di anteprima, come descritto nella precedente sezione HTTP.

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

Modificare il progetto Cloud utilizzato dallo script

In Impostazioni progetto, fai clic su Cambia progetto e inserisci l'ID progetto Cloud del progetto che hai registrato al Developer Preview Program (per impostazione predefinita, gli script di 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 Impostazioni progetto, attiva Mostra il file manifest "appsscript.json" nell'editor. Torna in Editor e aggiungi oauthScopes al file appscript.json per tutti gli ambiti di cui hai bisogno. Gli ambiti di 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"
  ]
}

Fornisci un'etichetta e una versione di anteprima

Tornando allo script, assicurati di aver aggiunto l'etichetta e la versione di anteprima appropriate come descritto nella sezione HTTP precedente. L'esempio di chiamata LIST al servizio Rubrics è il seguente:

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);
}