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 due considerazioni da fare quando si utilizzano le funzionalità di anteprima rispetto alla versione stabile Le API v1 sono:

  1. 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.
  2. 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:

  1. Librerie client generate dinamicamente
  2. Librerie client statiche fornite da Google
  3. 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 di anteprima 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.