Google Classroom eklentileri artık geliştiricilerin genel kullanımına sunuldu! Daha fazla bilgi edinmek için lütfen eklenti belgelerini inceleyin.

Bu sayfa, Cloud Translation API ile çevrilmiştir.

Önizleme API'lerine erişme

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

Kararlı v1 API ile karşılaştırıldığında önizleme özelliklerini kullanırken dikkate alınması gereken üç nokta şunlardır:

Google Cloud projesinin Google Workspace Geliştirici Önizleme Programı'na kayıtlı olması ve Google tarafından izin verilenler listesine eklenmesi gerekir.
Erken erişim veya önizleme programlarındaki API özellikleri standart istemci kitaplıklarında kullanıma sunulmaz ve varsayılan olarak HTTP üzerinden erişilemeyebilir.
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:

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

API'yi kullanmak için dinamik olarak oluşturulan veya Google tarafından sağlanan statik kitaplıkları kullanmanız önerilir. Kendi kitaplığınızı oluşturmanız gerekiyorsa istemci kitaplıkları oluşturma bölümüne bakın. Kendi kitaplığınızı oluşturma bu kılavuzun kapsamı dışındadır ancak önizleme etiketleri ve bunların Keşfet'teki rolü hakkında bilgi edinmek için dinamik kitaplıklar bölümünü incelemeniz gerekir.

Dinamik kitaplıklar

Python gibi dillerdeki kitaplıklar, Discovery hizmetinden alınan Discovery belgesini kullanarak çalışma zamanında istemci kitaplığını oluşturur.

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

Classroom API hizmeti için Discovery belgeleri (classroom.googleapis.com) şu uç noktada bulunabilir:

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

Önizleme API'leriyle çalışırken önemli olan nokta, uygun label değerini belirtmektir. Classroom genel önizlemelerinde bu etiket DEVELOPER_PREVIEW şeklindedir.

Python kitaplığını oluşturmak ve Classroom hizmetini önizleme yöntemleriyle başlatmak 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 oluşturulmalıdır. Bu kitaplıklar size sunulur ve önizleme özellikleri zaten dahil edilmiştir.

Herkese açık önizlemeler için Classroom istemci kitaplıklarını diğer Workspace Geliştirici Önizleme Programı istemci kitaplıkları ile birlikte bulabilirsiniz. Özel önizlemeler için, statik kitaplıklar oluşturmanız gerekiyorsa Google temsilcinizle iletişime geçin.

Önizleme özelliklerini içermeyen standart istemci kitaplıklarını içe aktarmak yerine bu yerel kitaplıkları kullanmak için normal bağımlılıklar yapılandırmanızı değiştirmeniz gerekebilir.

Örneğin, Go istemci kitaplığını kullanmak için replace yönergesini go.mod dosyanızda kullanarak yerel dizindeki bir modülü zorunlu kılmanız 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 işlemini (googleapis-classroom-1.0.4.tgz) package.json içinde 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ıların yanı sıra classroom-with-preview-features modülünü gerektirip bu modülden classroom hizmetini başlatın:

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ü belirtme

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

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

Sürüm belirtmek için isteklerde PreviewVersion alanı ayarlanı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()

Ö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 kullanılan previewVersion'yı salt okunur alan olarak da içerir. Örneğin, önceki CREATE çağrısından gelen yanıtta V1_20231110_PREVIEW değeri bulunur:

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 istekleri gönderirseniz yine de önizleme özelliklerini etkinleştirmeniz ve bir önizleme sürümü belirtmeniz gerekir. Bu işlem, label üstbilgisi ve yukarıda bahsedilen önizleme sürümü ile X-Goog-Visibilities ayarlanarak sorgu parametresi veya POST gövdesi alanı olarak yapılır (ilgili API referans belgelerine bakın). Herkese açık önizlemelerde etiket DEVELOPER_PREVIEW olur.

Örneğin, aşağıdaki curl isteği, Rubrics hizmetine uygun görünürlük etiketi ve önizleme sürümüyle bir 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

İstek gövdesinde önizleme sürümünü de belirtebilirsiniz. Örneğin, 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 belgelerinde açıklanmıştır.

Google Apps Komut Dosyası

Google Apps Komut Dosyası'ndan önizleme API'lerini çağırmak mümkündür. Ancak, normal Apps Komut Dosyası kullanımından birkaç fark vardır.

Komut dosyanızı, Geliştirici Önizleme Programı'na kaydolduğunuz Google Cloud projesini kullanacak şekilde yapılandırmanız gerekir.
Gelişmiş Hizmetler, önizleme yöntemlerini desteklemez. Bu nedenle, istekleri doğrudan HTTP ile yapmanız gerekir.
Ö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ıç kılavuzuna bakın. Ardından, önizleme API'lerini çağırmaya başlamak için aşağıdaki talimatları uygulayın:

Komut dosyası tarafından kullanılan 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 Komut Dosyası komut dosyaları genel bir proje kullanır). Yalnızca kayıtlı projeler önizleme yöntemlerini çağırabilir.

HTTP isteklerini yapılandırma

Ardından, Editor'da geri çağırmak istediğiniz yöntemin HTTP isteğini yapılandırın. Örneğin, hızlı başlangıç bölümünde, Classroom hizmetiyle listelenen kurslar şu şekilde 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 kullanılarak yapılan eşdeğer işlem şudur:

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ı çıkarılır ancak Apps Komut Dosyası'nda 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 dönerek 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 method page 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 geri 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 örnek LIST çağrısı şu şekilde 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);
}