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

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

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

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

المستخدم الذي يمكنه إدارة الأوصياء

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

جدول قوائم التحكم بالوصول (ACL) المتعلقة بالوصي حسب نوع المستخدم

المستويات

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

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

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

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

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

لغة Java

Classroom/snippets/src/main/java/CreateGuardianInvite.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')))

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

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

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

لغة Java

Classroom/snippets/src/main/java/CancelGuardian زيارة.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/ListGuardianInvitesByStudent.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 من خلال توفير مَعلمة حالات.

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

إذا كنت تريد تحديد المستخدمين الأوصياء النشطين على طالب معيّن، يمكنك استخدام طريقة 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()