Acessar APIs de visualização

Nesta página, descrevemos como acessar os recursos de visualização da API Classroom e especificar versões de pré-lançamento.

As duas considerações ao usar recursos de visualização em comparação com a API v1 estável são:

1. Os recursos da API em programas de acesso antecipado ou de pré-lançamento não são expostos nas bibliotecas de cliente padrão e podem não ser acessíveis por padrão via HTTP.
2. A qualquer momento, pode haver vários estados ou versões da API em pré-lançamento.

Ativar recursos de visualização em bibliotecas de cliente

Uma opção comum para usar a API Classroom é com uma biblioteca de cliente. Existem três tipos de bibliotecas de cliente:

1. Bibliotecas de cliente geradas dinamicamente
2. Bibliotecas de cliente estáticas fornecidas pelo Google
3. Sua própria biblioteca de cliente personalizada

A maneira recomendada de usar a API é usar bibliotecas estáticas geradas dinamicamente ou fornecidas pelo Google. Consulte Criar bibliotecas de cliente se precisar criar sua própria biblioteca. Criar sua própria biblioteca está fora do escopo deste guia, mas é importante consultar a seção bibliotecas dinâmicas para saber mais sobre os rótulos de visualização e o papel deles na Discovery.

Bibliotecas dinâmicas

Bibliotecas em linguagens como Python geram a biblioteca de cliente no ambiente de execução usando um documento de descoberta do serviço Discovery.

Um Documento de descoberta é uma especificação legível por máquina para descrever e consumir APIs REST. Ele é usado para criar bibliotecas de cliente, plug-ins de ambiente de desenvolvimento integrado e outras ferramentas que interagem com as APIs do Google. Um serviço pode fornecer vários documentos de descoberta.

Os documentos de descoberta do serviço da API Classroom (classroom.googleapis.com) podem ser encontrados no seguinte endpoint:

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

A diferença importante para trabalhar com APIs de visualização é especificar o label apropriado. Para visualizações públicas do Google Sala de Aula, esse marcador é DEVELOPER_PREVIEW.

Para gerar a biblioteca Python e instanciar o serviço Sala de Aula com métodos de visualização, especifique o URL de descoberta com o serviço, as credenciais e o rótulo adequados:

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)'

Consulte a documentação da biblioteca de cliente individual da API do Google para ver detalhes sobre cada linguagem.

Bibliotecas estáticas

As bibliotecas de cliente em linguagens como Java, Node.js, PHP, C# e Go precisam ser criadas com base na origem. Essas bibliotecas são fornecidas a você e têm os recursos em fase de pré-lançamento já incorporados.

Para prévias públicas, as bibliotecas de cliente do Google Sala de Aula podem ser encontradas com as outras bibliotecas de cliente do Programa de prévia para desenvolvedores do Google Workspace. Para visualizações particulares, fale com seu contato do Google se precisar de bibliotecas estáticas geradas.

Talvez seja necessário modificar sua configuração de dependências típica para usar essas bibliotecas locais em vez de importar as bibliotecas de cliente padrão, que não têm os recursos em fase de pré-lançamento.

Por exemplo, para usar a biblioteca de cliente Go, é necessário usar a diretiva replace no arquivo go.mod para exigir um módulo de um diretório local:

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

Como outro exemplo, se você estiver usando Node.js e npm, adicione o download da biblioteca de cliente Node.js (googleapis-classroom-1.0.4.tgz) como uma dependência local em 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"
  }
}

Em seguida, no aplicativo, exija o módulo classroom-with-preview-features, além das dependências regulares, e instancie o serviço classroom desse módulo:

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

...

Especificar uma versão de visualização da API

Independente de você usar uma biblioteca estática ou dinâmica, é necessário especificar a versão de pré-lançamento ao fazer chamadas de API para métodos com recursos de visualização.

As diferentes versões disponíveis e os recursos que elas incluem estão documentados no Roteiro da API Classroom. A documentação de referência dos métodos e campos também descreve em quais versões o método ou campo está disponível.

A especificação de uma versão é feita ao configurar o campo PreviewVersion nas solicitações. Por exemplo, para criar uma rubrica com a API de visualização Rubrics CRUD, defina previewVersion como V1_20231110_PREVIEW na solicitação 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()

Observação :as versões de pré-lançamento são temporárias, enquanto os recursos são validados para disponibilidade geral na API v1. O comportamento da versão de visualização está sujeito a mudanças após a janela de descontinuação. Consulte Roteiro da API Classroom para mais informações.

Os recursos associados a uma chamada de método de visualização também contêm o previewVersion usado na chamada como um campo somente leitura, para ajudar a entender qual versão está sendo usada. Por exemplo, a resposta da chamada CREATE anterior contém o valor 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",
  ...
}

Observação :a versão de visualização associada a um recurso corresponde à versão usada para recuperar o recurso, não necessariamente a chamada para criar o recurso. Se você fizer uma chamada GET, LIST ou PATCH futura com uma nova versão especificada, a nova versão será retornada.

Solicitações HTTP

Também é possível consumir a API Classroom diretamente com HTTP.

Se você fizer solicitações HTTP sem uma biblioteca de cliente, ainda será necessário ativar os recursos de visualização para especificar uma versão de pré-lançamento. Isso é feito configurando um label com um cabeçalho X-Goog-Visibilities e a versão de visualização mencionada como um parâmetro de consulta ou um campo de corpo do POST. Para visualizações públicas, o rótulo é DEVELOPER_PREVIEW.

Por exemplo, a seguinte solicitação curl faz uma chamada LIST para o serviço Rubrics com o rótulo de visibilidade e a versão de visualização adequados:

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

Também é possível especificar a versão de visualização no corpo da solicitação, por exemplo, ao fazer uma solicitação 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

A API para cada solicitação HTTP é descrita na documentação REST.