Accedi alle API di anteprima

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

Le due considerazioni da fare quando si utilizzano le funzionalità di anteprima rispetto all'API stabile v1 sono:

1. Le funzionalità API nei programmi di accesso in anteprima o in anteprima non sono esposte nelle librerie client standard e potrebbero non essere accessibili per impostazione predefinita tramite HTTP.
2. In qualsiasi momento, potrebbero essere disponibili più stati o versioni dell'API in anteprima.

Abilita le funzionalità di anteprima nelle librerie client

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

1. Librerie client generate dinamicamente
2. Librerie client statiche fornite da Google
3. La tua libreria client personalizzata

L'utilizzo di librerie statiche generate dinamicamente o fornite da Google è il modo consigliato per utilizzare l'API. Se hai bisogno di creare la tua libreria, consulta l'articolo sulla creazione di librerie client. La creazione della tua libreria 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 dal servizio di rilevamento.

Un documento discovery è una specifica leggibile dalle macchine per la descrizione e l'utilizzo delle API REST. Viene utilizzato per creare librerie client, plug-in IDE e altri strumenti che interagiscono con le API di Google. Un servizio può 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 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 i metodi di anteprima, puoi specificare l'URL di rilevamento 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 i dettagli su ciascuna lingua, consulta la documentazione relativa alla libreria 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 ti 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 gli sviluppatori di Workspace. Per le anteprime private, rivolgiti al tuo contatto Google se hai bisogno di generare librerie statiche.

Potrebbe essere necessario modificare la configurazione delle dipendenze tipica per utilizzare queste librerie locali anziché importare le librerie client standard, che non offrono le funzionalità in 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 ulteriore 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, nell'applicazione, richiedi il modulo classroom-with-preview-features oltre alle normali dipendenze 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 di anteprima dell'API

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.

Per specificare una versione, devi impostare il campo PreviewVersion nelle richieste. Ad esempio, per creare una griglia 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()

Nota: le versioni in anteprima sono destinate a essere temporanee, mentre le funzionalità vengono convalidate per la disponibilità generale nell'API v1. Il comportamento della versione in anteprima è soggetto a variazioni dopo il periodo di deprecazione. Per ulteriori informazioni, consulta la Roadmap dell'API Classroom.

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

Nota: la versione di anteprima associata a una risorsa corrisponde alla versione utilizzata per recuperare la risorsa, non necessariamente alla chiamata per creare la risorsa; se effettui una chiamata GET, LIST o PATCH futura con una nuova versione specificata, viene restituita la nuova versione.

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 e specificare una versione di anteprima. A questo scopo, imposta label con un'intestazione X-Goog-Visibilities e la versione di anteprima sopra indicata come parametro di query o campo corpo POST. 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à appropriata e la versione di anteprima:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_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 si esegue una richiesta POST:

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

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