Önizleme API'lerine erişme

Bu sayfada, Classroom API önizleme özelliklerine ve önizleme sürümlerini belirtir.

Kararlı sürüme kıyasla önizleme özelliklerini kullanırken dikkat edilmesi gereken üç nokta v1 API'leri şunlardır:

  1. Çağrı yapan Google Cloud projesi, Google Workspace'e kayıtlı olmalıdır. Geliştirici Önizleme Programı'na gidin ve Google tarafından listelenen izin verilenler listesine ekleyin.
  2. Erken erişim veya önizleme programlarındaki API özellikleri ve HTTP üzerinden varsayılan olarak erişilemeyebilir.
  3. Herhangi bir zamanda, önizle.

İstemci kitaplıklarında önizleme özelliklerini etkinleştirme

Classroom API'yi kullanmak için yaygın olarak kullanılan bir seçenek, istemci kitaplığıdır. Orada üç farklı istemci kitaplığı türüdür:

  1. Dinamik olarak oluşturulmuş istemci kitaplıkları
  2. Google tarafından sağlanan statik istemci kitaplıkları
  3. Kendi özel istemci kitaplığınız

Dinamik olarak oluşturulmuş veya Google tarafından sağlanan statik kitaplıkları kullanarak kullanmanızı öneririz. Yapmanız gereken işlemler istemci kitaplıkları oluşturma başlıklı makaleye göz atın. kendi kitaplığınızı oluşturabilirsiniz. Kendi kitaplığınızı oluşturmak bu politikanın kapsamı dışındadır kılavuzu vardır, ancak hakkında bilgi edinmek için dinamik kitaplıklar bölümünü incelemeniz Discovery'deki rollerini ve önizlemelerini gözden geçirin.

Dinamik kitaplıklar

Python gibi dillerdeki kitaplıklar, istemci kitaplığını çalışma zamanında Keşif hizmetinden bir Keşif Dokümanı

Keşif Belgesi, Keşif Belgesi (Keşif Belgesi) aşağıdakileri açıklamak için makine tarafından tam olarak bunu yapabilirsiniz. Bu API, istemci kitaplıkları, IDE eklentileri ve etkileşimi olan diğer araçlar. Bir hizmet birden fazla belgeleri inceleyeceğiz.

Classroom API hizmeti (classroom.googleapis.com) için Discovery Dokümanları aşağıdaki uç noktada bulunabilir:

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

Önizleme API'leriyle çalışmanın önemli farkı, uygun label. Classroom'daki herkese açık önizlemeler için, ilgili etiketin DEVELOPER_PREVIEW

Python kitaplığını oluşturmak ve Classroom hizmetini yöntem kullanıyorsanız Keşif URL'sini uygun hizmetle belirtebilir, ve etiket ekleyin:

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

Her bir istemciyle ilgili ayrıntılı bilgi için ilgili Google API istemci kitaplığı dokümanlarına bakın dili'ne dokunun.

Statik kitaplıklar

Java, Node.js, PHP, C# ve Go gibi dillerde istemci kitaplıkları oluşturulmalıdır sağlayabilir. Önizleme özelliklerine sahip olan bu kitaplıklar sizin için sağlanır dahil edilmiştir.

Herkese açık önizlemeler için Classroom istemci kitaplıkları, Workspace Geliştirici Önizleme Programı istemci kitaplıkları. Gizli önizlemelerde statik kitaplık oluşturulması gerekiyorsa Google temsilcinizle iletişime geçin.

Bunları kullanmak için tipik bağımlılık yapılandırmanızı değiştirmeniz gerekebilir yapmayan standart istemci kitaplıklarını içe aktarmak yerine önizleme özelliklerine sahip olursunuz.

Örneğin, Go istemci kitaplığını kullanmak için replace yönergesini go.mod dosyanızdaki yerel dizinden bir modül gerektirecek şekilde ekleyebilirsiniz:

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

Başka bir örnek olarak, Node.js ve npm kullanıyorsanız Node.js istemcisini yerel bağımlılık olarak kitaplık indirme (googleapis-classroom-1.0.4.tgz) 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"
  }
}

Ardından uygulamanızda classroom-with-preview-features modülünü gerekli kılıyor ve classroom hizmetini örneklendirmek için kullanabileceğiniz bulabilirsiniz:

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

...

Önizleme API sürümü belirtin

Statik veya dinamik kitaplıktan bağımsız olarak, önizleme özelliklerini içeren yöntemlere API çağrıları yaparken kullanılacak önizleme sürümü

Kullanıma sunulan farklı sürümler ve içerdikleri özellikler açıklanmıştır. Classroom API Yol Haritası başlıklı makaleyi inceleyin. Yöntem ve referans belgeleri alanları, yöntemin veya alanın hangi sürümlerde kullanılabildiğini de açıklar.

Sürüm, isteklerde PreviewVersion alanı ayarlanarak yapılır. Örneğin, Puan Anahtarları CRUD önizleme API'si ile bir puan anahtarı oluşturmak için CREATE isteğinde V1_20231110_PREVIEW için previewVersion:

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

Önizleme yöntemi çağrısıyla ilişkili kaynaklar, Aşağıdakileri anlamanıza yardımcı olmak için görüşmede salt okunur alan olarak previewVersion kullanıldı: yardımcı oluyorum. Örneğin, önceki CREATE çağrı, V1_20231110_PREVIEW değerini içerir:

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

HTTP istekleri

Classroom API'yi doğrudan HTTP ile kullanmak da mümkündür.

İstemci kitaplığı olmadan HTTP isteklerinde bulunursanız yine de etkinleştirmeniz gerekir. önizleme özellikleri bir önizleme sürümünü belirtir. Bu işlem, bir label bir X-Goog-Visibilities başlığı ve daha önce sözü edilen önizleme sürümünü içeren bir sorgu parametresi veya POST gövde alanı (ilgili API'ya bakın) referans belgeler). Herkese açık önizlemeler için etiket DEVELOPER_PREVIEW şeklindedir.

Örneğin, aşağıdaki curl isteği, Puan Anahtarları hizmetine bir LIST çağrısı yapıyor uygun görünürlük etiketiyle ve önizleme sürümüyle değiştirin:

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

Önizleme sürümünü istek gövdesinde de belirtebilirsiniz. Örneğin, POST isteği gönderme:

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

Her HTTP isteğiyle ilgili API, REST belgelerinde açıklanmıştır.

Google Apps Komut Dosyası

Google Apps Komut Dosyası'ndan önizleme API'leri çağrılabilir. Ancak, tipik Apps Komut Dosyası kullanımına göre birkaç farklılık gösterir.

  1. Komut dosyanızı, kullandığınız Google Cloud projesini kullanacak şekilde yapılandırmanız gerekir Geliştirici Önizleme Programı'na kayıtlı olmanız gerekir.
  2. Gelişmiş Hizmetler önizleme yöntemlerini desteklemez. Bu nedenle isteklerini doğrudan HTTP ile karşılaştırmaktır.
  3. Önceki HTTP bölümü.

Bilgi edinmek için ilgili hızlı başlangıç kılavuzunu inceleyin Apps Komut Dosyası'na göz atın ve temel bir proje oluşturun. Ardından şunları uygulayın: önizleme API'lerini çağırmaya başlama talimatlarını inceleyin:

Komut dosyasının kullandığı Cloud projesini değiştirin

Proje Ayarları'nda Projeyi değiştir'i tıklayın ve Geliştirici Programı'na kaydettiğiniz projenin Cloud projesi kimliği Önizleme Programı (varsayılan olarak Apps Komut Dosyası'ndaki komut dosyaları genel bir proje kullanır). Yalnızca kayıtlı önizleme yöntemlerini çağırabilir.

HTTP isteklerini yapılandırın

Ardından, geri çağırmak istediğiniz yöntemin HTTP isteğini yapılandırın Düzenleyici. Örneğin, hızlı başlangıç kılavuzunda, Classroom ile dersleri listeleme hizmet şöyle görünür:

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

Doğrudan HTTP kullanan eşdeğer işlem:

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

Gelişmiş hizmetler kullanılırken gerekli OAuth kapsamları tahmin edilir ancak Apps Komut Dosyası'nda Google API'lerine doğrudan HTTP çağrıları yapmak için, ve uygun kapsamları manuel olarak ekleyin.

Proje Ayarları'nda, Show "appsscript.json" seçeneğini etkinleştirin manifesto dosyasını düzenleyici'ye gidin. Düzenleyici'ye geri dönüp şunun için appscript.json dosyasına oauthScopes ekleyin: seçenekleri belirleyebilirsiniz. Belirli bir yöntemin kapsamları referans sayfanız. Örneğin, courses.courseWork.rubrics liste yöntemine bakın" öğrenin.

Güncellenen appscript.json dosyası aşağıdaki gibi görünebilir:

{
  "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"
  ]
}

Etiket ve önizleme sürümü sağlayın

Komut dosyanıza geri dönüp uygun etiketi ve önizlemeyi eklediğinizden emin olun. sürümünü yükseltmeniz gerekir. Örnek LIST çağrısı Puan Anahtarları hizmeti şöyle görünür:

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