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

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

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

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

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

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

المستويات

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

• يسمح لك النطاق https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly بعرض الأوصياء الخاصين بالمستخدم.
• يتيح لك https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly عرض الأوصياء وطلبات الأوصياء للطلاب الذين يُدرِّسهم المستخدم أو يشرف عليهم.
• يتيح لك https://www.googleapis.com/auth/classroom.guardianlinks.students عرض وتعديل الأوصياء وطلبات الأوصياء للطلاب الذين يعلّمهم المستخدم أو يشرف عليهم.

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

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

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

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

Java

classroom/snippets/src/main/java/CreateGuardianInvitation.java

العرض على GitHub

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': '[e-mail]',
}
guardianInvitation = service.userProfiles().guardianInvitations().create(
                      studentId='[e-mail]',
                          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

العرض على GitHub

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='[e-mail]',
  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

عرض على GitHub

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='[e-mail]').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

العرض على GitHub

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='[e-mail]').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')))

ملاحظة: يحتوي كل ردّ من الوصي على UserProfile للوصي. يجب توفّر نطاقات إضافية لعرض عنوان البريد الإلكتروني وصورة الملف الشخصي المرفقَين بهذا الملف الشخصي، ولا يمكن لأحد الوصول إليه سوى المشرفين.

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

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

Java

classroom/snippets/src/main/java/DeleteGuardian.java

العرض على GitHub

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='[e-mail]',
                                        guardianId='[e-mail]').execute()