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

In questa pagina viene descritto come accedere alle funzionalità di anteprima dell'API Classroom e e specificare le versioni in anteprima.

Le tre considerazioni da fare quando si utilizzano le funzionalità di anteprima rispetto alla versione stabile Le API v1 sono:

Il progetto Google Cloud chiamante deve essere registrato in Google Workspace Programma Anteprima per gli sviluppatori e consentire l'accesso elencato da Google.
Le funzionalità API nei programmi di accesso in anteprima o di anteprima non sono visibili nella librerie client standard e potrebbero non essere accessibili per impostazione predefinita tramite HTTP.
In un dato momento potrebbero esserci più stati, o versioni dell'API, in l'anteprima.

Abilita le funzionalità di anteprima nelle librerie client

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

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

L'utilizzo delle librerie statiche generate dinamicamente o fornite da Google è metodo consigliato per usare l'API. Se necessario, consulta Creare librerie client creare la tua raccolta. La creazione della tua libreria non rientra nell'ambito di questa procedura. guida, ma ti consigliamo di consultare la sezione Librerie dinamiche per saperne di più visualizzare in anteprima le etichette e il 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 dal servizio di rilevamento.

Un documento di rilevamento è una specifica leggibile da macchina per descrivere e che utilizzano le API REST. È utilizzato per creare librerie client, plug-in IDE e che interagiscono con le API di Google. Un servizio può offrire più servizi documenti di rilevamento.

Documenti di rilevamento per il servizio API Classroom (classroom.googleapis.com) disponibile al seguente endpoint:

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

L'importante differenza nell'uso delle API di anteprima è specificare label appropriati. 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 rilevamento con il servizio appropriato, credenziali ed etichetta:

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 singola API di Google, consulta la documentazione sulla libreria client lingua.

Librerie statiche

È necessario creare librerie client in linguaggi come Java, Node.js, PHP, C# e Go dall'origine. Queste librerie ti vengono fornite e ti offrono le funzionalità in anteprima già incorporati.

Per le anteprime pubbliche, le librerie client di Classroom sono disponibili con l'altro Librerie client del Programma Anteprima per gli sviluppatori di Workspace. Per le anteprime private, Rivolgiti al tuo contatto Google se hai bisogno di generare librerie statiche.

Per utilizzare queste dipendenze, potrebbe essere necessario modificare la configurazione tipica 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 replace nel tuo 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 ulteriore esempio, se utilizzi Node.js e npm, aggiungi il client Node.js download della libreria (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"
  }
}

Nella tua applicazione, richiedi il modulo classroom-with-preview-features oltre alle dipendenze regolari e creare un'istanza per il servizio classroom da questo 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 dal fatto che utilizzi una libreria statica o dinamica, devi specificare il quando si effettuano 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 descrivono anche le versioni in cui è disponibile il metodo o il campo.

Per specificare una versione, devi impostare il campo PreviewVersion nelle richieste. Ad esempio, per creare una griglia con l'API di anteprima CRUD Griglie, devi impostare Da previewVersion a 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 previewVersion utilizzato nella chiamata come campo di sola lettura, per aiutarti a comprendere la versione in uso. Ad esempio, la risposta dalla precedente richiesta CREATE la chiamata 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 abilitare le funzionalità di anteprima specificano una versione di anteprima. Per farlo, devi impostare un label con un'intestazione X-Goog-Visibilities e la versione di anteprima di cui sopra come un parametro di query o un campo POST del corpo (vedi le singole API appropriate documentazione di riferimento). Per le anteprime pubbliche, l'etichetta è DEVELOPER_PREVIEW.

Ad esempio, la seguente richiesta curl effettua una chiamata LIST al servizio Griglie. 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 dell'anteprima nel corpo della richiesta, ad esempio quando per effettuare 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 relativa al REST.

Google Apps Script

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

Devi configurare lo script in modo da utilizzare qualsiasi progetto Google Cloud Registrato al Programma Anteprima per gli sviluppatori.
I Servizi avanzati non supportano i metodi di anteprima, quindi è necessario effettuare richieste direttamente con HTTP.
Devi fornire un'etichetta e una versione di anteprima, come descritto nella sezione Sezione HTTP.

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

Cambia 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 in Developer Programma Anteprima (per impostazione predefinita, gli script Apps Script usano un progetto generico). Solo registrati i progetti possono richiamare metodi di anteprima.

Configura richieste HTTP

Quindi, configura la richiesta HTTP di qualsiasi metodo che vuoi richiamare Editor. Ad esempio, nella guida rapida, elencare i corsi con Classroom ha questo 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 si utilizzano i servizi avanzati, vengono dedotti gli ambiti OAuth richiesti, ma per chiamate HTTP dirette alle API di Google in Apps Script, è necessario aggiungere manualmente gli ambiti appropriati.

In Impostazioni progetto, attiva Mostra "appsscript.json". in un file manifest Editor. Torna in Editor, aggiungi oauthScopes al file appscript.json per a seconda degli ambiti di cui hai bisogno. Gli ambiti per un determinato metodo sono elencati nel pagina di riferimento. Ad esempio, vedi il metodo dell'elenco courses.courseWork.rubrics list .

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 visualizza l'anteprima della versione

Torna allo script, assicurati di aver aggiunto l'etichetta e l'anteprima appropriate come descritto nella precedente sezione relativa a HTTP. La chiamata LIST di esempio a il servizio Griglie 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);
}