Önizleme API'lerine erişme

Bu sayfada, Classroom API önizleme özelliklerine nasıl erişebileceğiniz ve önizleme sürümlerini nasıl belirtebileceğiniz açıklanmaktadır.

Önizleme özelliklerini kullanırken kararlı v1 API'ye kıyasla dikkat edilmesi gereken üç nokta vardır:

  1. Arayan Google Cloud projesi, Google Workspace Geliştirici Önizleme Programı'na kayıtlı ve Google tarafından izin verilenler listesine eklenmiş olmalıdır.
  2. Erken erişim veya önizleme programlarındaki API özellikleri standart istemci kitaplıklarında gösterilmez ve varsayılan olarak HTTP üzerinden erişilemeyebilir.
  3. Herhangi bir zamanda, önizlemede birden fazla API durumu veya sürümü olabilir.

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

Classroom API'yi kullanmak için yaygın bir seçenek istemci kitaplığıdır. Üç tür istemci kitaplığı vardı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

API'yi kullanmanın önerilen yolu, dinamik olarak oluşturulan veya Google tarafından sağlanan statik kitaplıkları kullanmaktır. Kendi kitaplığınızı oluşturmanız gerekiyorsa istemci kitaplığı oluşturma bölümüne bakın. Kendi kitaplığınızı oluşturma işlemi bu kılavuzun kapsamı dışındadır ancak önizleme etiketleri ve Discovery'deki rolleri hakkında bilgi edinmek için dinamik kitaplıklar bölümünü incelemeniz gerekir.

Dinamik kitaplıklar

Python gibi dillerdeki kitaplıklar, Keşif hizmetinden bir Keşif Belgesi kullanarak istemci kitaplığını çalışma zamanında oluşturur.

Keşif belgesi, REST API'leri tanımlamak ve kullanmak için makine tarafından okunabilir bir spesifikasyondur. İstemci kitaplıkları, IDE eklentileri ve Google API'leriyle etkileşime geçen diğer araçları oluşturmak için kullanılır. Bir hizmet birden fazla keşif dokümanı sağlayabilir.

Classroom API hizmetinin (classroom.googleapis.com) Discovery belgelerini aşağıdaki uç noktada bulabilirsiniz:

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

Önizleme API'leriyle çalışırken dikkat edilmesi gereken önemli nokta, uygun label değerini belirtmektir. Classroom'un herkese açık önizlemelerinde bu etiket DEVELOPER_PREVIEW şeklindedir.

Python kitaplığını oluşturmak ve Classroom hizmetini önizleme yöntemleriyle örneklemek için Discovery URL'sini uygun hizmet, kimlik bilgileri ve etiketle belirtebilirsiniz:

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 dil hakkında ayrıntılı bilgi için ilgili Google API istemci kitaplığı belgelerine bakın.

Statik kitaplıklar

Java, Node.js, PHP, C# ve Go gibi dillerdeki istemci kitaplıkları kaynaktan derlenmelidir. Bu kitaplıklar sizin için sağlanır ve önizleme özellikleri zaten dahildir.

Herkese açık önizlemelerde Classroom istemci kitaplıkları, diğer Workspace Geliştirici Önizleme Programı istemci kitaplıklarıyla birlikte bulunabilir. Statik kitaplıkların oluşturulması gerekiyorsa özel önizlemeler için Google temsilcinizle iletişime geçin.

Önizleme özelliklerine sahip olmayan standart istemci kitaplıklarını içe aktarmak yerine bu yerel kitaplıkları kullanmak için genel bağımlılık yapılandırmanızı değiştirmeniz gerekebilir.

Örneğin, Go istemci kitaplığını kullanmak için go.mod dosyanızda replace yönergesini kullanarak yerel bir dizinden modül istemeniz gerekir:

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 istemci kitaplığı indirme dosyasını (googleapis-classroom-1.0.4.tgz) package.json dosyasına yerel bağımlılık olarak ekleyin:

{
  "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 normal bağımlılara ek olarak classroom-with-preview-features modülünü zorunlu kılın ve bu modülden classroom hizmetini örnekleyin:

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

...

Bir önizleme API sürümü belirtin

Statik veya dinamik kitaplık kullanıp kullanmadığınızdan bağımsız olarak, önizleme özelliklerine sahip yöntemlere API çağrısı yaparken önizleme sürümünü belirtmeniz gerekir.

Kullanılabilen farklı sürümler ve bu sürümlerde yer alan özellikler Classroom API Yol Haritası'nda açıklanmıştır. Yöntemler ve alanlarla ilgili referans dokümanlarında, yöntemin veya alanın hangi sürümlerde kullanılabildiği de açıklanır.

Sürüm belirtme işlemi, isteklerde PreviewVersion alanı ayarlanarak yapılır. Örneğin, Rubrics CRUD önizleme API'si ile puan anahtarı oluşturmak için CREATE isteğinde previewVersion değerini V1_20231110_PREVIEW olarak ayarlarsınız:

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

Bir önizleme yöntemi çağrısıyla ilişkili kaynaklar, hangi sürümü kullandığınızı anlamanıza yardımcı olmak için çağrıda salt okunur alan olarak kullanılan previewVersion değerini de içerir. Örneğin, önceki CREATE çağrısından gelen yanıt 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 de kullanabilirsiniz.

İstemci kitaplığı olmadan HTTP istekleri gönderiyorsanız önizleme özelliklerini etkinleştirmeniz ve bir önizleme sürümü belirtmeniz gerekir. Bu işlem, X-Goog-Visibilities başlığı ve yukarıda belirtilen önizleme sürümü ile bir label ayarlayarak ya bir sorgu parametresi veya POST gövde alanı olarak yapılır (ilgili API referans dokümanlarına bakın). Herkese açık önizlemeler için etiket DEVELOPER_PREVIEW'tür.

Örneğin, aşağıdaki curl isteği, uygun görünürlük etiketi ve önizleme sürümüyle Rubrics hizmetine LIST çağrısı yapar:

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 (ör. POST isteği gönderirken):

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ği için API, REST dokümanlarında açıklanmaktadır.

Google Apps Komut Dosyası

Google Apps Komut Dosyası'ndan önizleme API'lerini çağırabilirsiniz. Ancak, tipik Apps Komut Dosyası kullanımından birkaç farkı vardır.

  1. Komut dosyanızı, Geliştirici Önizleme Programı'na kaydettiğiniz Google Cloud projesini kullanacak şekilde yapılandırmanız gerekir.
  2. Gelişmiş Hizmetler, önizleme yöntemlerini desteklemediğinden istekleri doğrudan HTTP ile göndermeniz gerekir.
  3. Önceki HTTP bölümünde açıklandığı gibi bir etiket ve önizleme sürümü sağlamanız gerekir.

Apps Komut Dosyası'nı tanımak ve temel bir proje oluşturmak için ilgili hızlı başlangıç bölümüne bakın. Ardından, önizleme API'lerini çağırmaya başlamak için aşağıdaki talimatları uygulayın:

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

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

HTTP isteklerini yapılandırma

Ardından, geri çağırılmak istediğiniz yöntemin HTTP isteğini Düzenleyici'de yapılandırın. Örneğin, hızlı başlangıç bölümünde, Classroom hizmetini kullanarak dersleri listeleme işlemi aşağıdaki gibi 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 Script'te Google API'lerine doğrudan HTTP çağrıları yapmak için uygun kapsamları manuel olarak eklemeniz gerekir.

Proje Ayarları'nda "appsscript.json" manifest dosyasını düzenleyicide göster'i etkinleştirin. Düzenleyici'ye geri dönüp ihtiyacınız olan kapsamlar için appscript.json dosyasına oauthScopes ekleyin. Belirli bir yöntemin kapsamları referans sayfasında listelenir. Örneğin, courses.courseWork.rubrics list yöntemi sayfasına bakın.

Güncellenen appscript.json dosyası şu şekilde 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ğlama

Komut dosyanıza dönerek önceki HTTP bölümünde açıklandığı gibi uygun etiketi ve önizleme sürümünü eklediğinizden emin olun. Rubrics hizmetine yapılan LIST çağrısı örneği aşağıdaki gibi 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);
}