إدارة الأوصياء

يمثّل مصدر الأوصياء مستخدمًا، مثل أحد الوالدَين، يتلقّى معلومات عن دورات أحد الطلاب وواجباته. يجب دعوة الوصي، الذي لا يكون عادةً عضوًا في نطاق Classroom الخاص بالطالب، باستخدام عنوان بريده الإلكتروني ليصبح وصيًا.

تنشئ هذه الدعوة مورد GuardianInvitation بحالة PENDING. يتلقّى المستخدم بعد ذلك رسالة إلكترونية تطلب منه قبول الدعوة. إذا لم يكن عنوان البريد الإلكتروني مرتبطًا بحساب على Google، سيُطلَب من المستخدم إنشاء حساب قبل قبول الدعوة.

عندما تكون حالة الدعوة هي PENDING، يمكن للمستخدم قبول الدعوة، ما يؤدي إلى إنشاء مورد حارس ويضع علامة على GuardianInvitation بحالة COMPLETED. قد تصبح الدعوة أيضًا COMPLETED إذا انتهت صلاحيتها، أو إذا ألغى مستخدم مفوَّض الدعوة (على سبيل المثال، باستخدام PatchGuardianInvitation). يمكن أيضًا أن ينهي أحد الوصيين أو المعلّمين في Classroom أو أحد المشرفين علاقة الوصي باستخدام واجهة مستخدم Classroom أو طريقة DeleteGuardian.

مَن يمكنه إدارة الأوصياء

يوضّح الجدول التالي الإجراءات التي يمكن تنفيذها في ما يتعلّق بالأوصياء، وفقًا لنوع المستخدم الذي تم مصادقة هويته حاليًا:

جدول قوائم التحكّم في الوصول ذات الصلة بـ "الحارس" حسب نوع المستخدم

المستويات

هناك ثلاثة نطاقات تتيح لك إدارة الأوصياء:

الإجراءات الشائعة

يصف هذا القسم بعض الإجراءات الشائعة التي يمكن أن يتّخذها الوصي والتي قد تحتاج إلى تنفيذها باستخدام Google Classroom API.

إنشاء دعوة وصي

يوضّح المثال التالي كيفية إنشاء دعوة لأحد الأوصياء باستخدام الإجراء التالي: userProfiles.guardianInvitations.create():

Java

classroom/snippets/src/main/java/CreateGuardianInvitation.java
GuardianInvitation guardianInvitation = null;

/* Create a GuardianInvitation object with state set to PENDING. See
https://developers.google.com/classroom/reference/rest/v1/userProfiles.guardianInvitations#guardianinvitationstate
for other possible states of guardian invitations. */
GuardianInvitation content =
    new GuardianInvitation()
        .setStudentId(studentId)
        .setInvitedEmailAddress(guardianEmail)
        .setState("PENDING");
try {
  guardianInvitation =
      service.userProfiles().guardianInvitations().create(studentId, content).execute();

  System.out.printf("Invitation created: %s\n", guardianInvitation.getInvitationId());
} catch (GoogleJsonResponseException e) {
  // TODO (developer) - handle error appropriately
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf("There is no record of studentId: %s", studentId);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return guardianInvitation;

Python

guardianInvitation = {
  'invitedEmailAddress': 'guardian@gmail.com',
}
guardianInvitation = service.userProfiles().guardianInvitations().create(
                      studentId='student@mydomain.edu',
                          body=guardianInvitation).execute()
print("Invitation created with id: {0}".format(guardianInvitation.get('invitationId')))

تتضمّن النتيجة معرّفًا يحدّده الخادم ويمكن استخدامه للإشارة إلى GuardianInvitation.

إلغاء دعوة أحد الأوصياء

لإلغاء دعوة، عدِّل حالة الدعوة من PENDING إلى COMPLETE من خلال استدعاء الطريقة userProfiles.guardianInvitations.patch(). يُرجى العِلم أنّ هذه هي الطريقة الوحيدة حاليًا لإزالة دعوة.

Java

classroom/snippets/src/main/java/CancelGuardianInvitation.java
GuardianInvitation guardianInvitation = null;

try {
  /* Change the state of the GuardianInvitation from PENDING to COMPLETE. See
  https://developers.google.com/classroom/reference/rest/v1/userProfiles.guardianInvitations#guardianinvitationstate
  for other possible states of guardian invitations. */
  GuardianInvitation content =
      service.userProfiles().guardianInvitations().get(studentId, invitationId).execute();
  content.setState("COMPLETE");

  guardianInvitation =
      service
          .userProfiles()
          .guardianInvitations()
          .patch(studentId, invitationId, content)
          .set("updateMask", "state")
          .execute();

  System.out.printf(
      "Invitation (%s) state set to %s\n.",
      guardianInvitation.getInvitationId(), guardianInvitation.getState());
} catch (GoogleJsonResponseException e) {
  // TODO (developer) - handle error appropriately
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf(
        "There is no record of studentId (%s) or invitationId (%s).", studentId, invitationId);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return guardianInvitation;

Python

guardian_invite = {
     'state': 'COMPLETE'
}
guardianInvitation = service.userProfiles().guardianInvitations().patch(
  studentId='student@mydomain.edu',
  invitationId=1234, # Replace with the invitation ID of the invitation you want to cancel
  updateMask='state',
  body=guardianInvitation).execute()

عرض دعوات لطالب محدّد

يمكنك الحصول على قائمة بجميع الدعوات التي تم إرسالها لطالب معيّن باستخدام طريقة userProfiles.guardianInvitations.list():

Java

classroom/snippets/src/main/java/ListGuardianInvitationsByStudent.java
List<GuardianInvitation> guardianInvitations = new ArrayList<>();
String pageToken = null;

try {
  do {
    ListGuardianInvitationsResponse response =
        service
            .userProfiles()
            .guardianInvitations()
            .list(studentId)
            .setPageToken(pageToken)
            .execute();

    /* Ensure that the response is not null before retrieving data from it to avoid errors. */
    if (response.getGuardianInvitations() != null) {
      guardianInvitations.addAll(response.getGuardianInvitations());
      pageToken = response.getNextPageToken();
    }
  } while (pageToken != null);

  if (guardianInvitations.isEmpty()) {
    System.out.println("No guardian invitations found.");
  } else {
    for (GuardianInvitation invitation : guardianInvitations) {
      System.out.printf("Guardian invitation id: %s\n", invitation.getInvitationId());
    }
  }
} catch (GoogleJsonResponseException e) {
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf("There is no record of studentId (%s).", studentId);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return guardianInvitations;

Python

guardian_invites = []
page_token = None

while True:
    response = service.userProfiles().guardianInvitations().list(
                                      studentId='student@mydomain.edu').execute()
    guardian_invites.extend(response.get('guardian_invites', []))
    page_token = response.get('nextPageToken', None)
    if not page_token:
        break

if not courses:
    print('No guardians invited for this {0}.'.format(response.get('studentId')))
else:
    print('Guardian Invite:')
    for guardian in guardian_invites:
        print('An invite was sent to '.format(guardian.get('id'),
                                              guardian.get('guardianId')))

سيتم عرض PENDING دعوة فقط تلقائيًا. بصفتك مشرفًا للنطاق، يمكنك أيضًا استرداد الدعوات في الحالة COMPLETED من خلال تقديم مَعلمة states.

إدراج الأوصياء النشطين

إذا كنت تريد تحديد المستخدمين الذين هم الأوصياء النشطين لطالب معيّن، يمكنك استخدام طريقة userProfiles.guardians.list(). الوصي النشط هو الوصي الذي قبل دعوة البريد الإلكتروني.

Java

classroom/snippets/src/main/java/ListGuardians.java
List<Guardian> guardians = new ArrayList<>();
String pageToken = null;

try {
  do {
    ListGuardiansResponse response =
        service.userProfiles().guardians().list(studentId).setPageToken(pageToken).execute();

    /* Ensure that the response is not null before retrieving data from it to avoid errors. */
    if (response.getGuardians() != null) {
      guardians.addAll(response.getGuardians());
      pageToken = response.getNextPageToken();
    }
  } while (pageToken != null);

  if (guardians.isEmpty()) {
    System.out.println("No guardians found.");
  } else {
    for (Guardian guardian : guardians) {
      System.out.printf(
          "Guardian name: %s, guardian id: %s, guardian email: %s\n",
          guardian.getGuardianProfile().getName().getFullName(),
          guardian.getGuardianId(),
          guardian.getInvitedEmailAddress());
    }
  }

} catch (GoogleJsonResponseException e) {
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf("There is no record of studentId (%s).", studentId);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return guardians;

Python

guardian_invites = []
page_token = None

while True:
    response = service.userProfiles().guardians().list(studentId='student@mydomain.edu').execute()
    guardian_invites.extend(response.get('guardian_invites', []))
    page_token = response.get('nextPageToken', None)
    if not page_token:
        break

if not courses:
    print('No guardians invited for this {0}.'.format(response.get('studentId')))
else:
    print('Guardian Invite:')
    for guardian in guardian_invites:
        print('An invite was sent to '.format(guardian.get('id'),
                                              guardian.get('guardianId')))

إزالة الأوصياء

يمكنك أيضًا إزالة وصي من حساب طالب باستخدام الطريقة userProfiles.guardians.delete():

Java

classroom/snippets/src/main/java/DeleteGuardian.java
try {
  service.userProfiles().guardians().delete(studentId, guardianId).execute();
  System.out.printf("The guardian with id %s was deleted.\n", guardianId);
} catch (GoogleJsonResponseException e) {
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf("There is no record of guardianId (%s).", guardianId);
  }
}

Python

service.userProfiles().guardians().delete(studentId='student@mydomain.edu',
                                        guardianId='guardian@gmail.com').execute()
السابق
إنشاء حسابات المعلّمين والطلاب وإدارتها