إنشاء الأوصياء وإدارتهم

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

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

عندما تتم دعوة المستخدم وقبل أن يقبل الدعوة، تكون حالة GuardianInvitation هي PENDING. بعد أن يقبل المستخدم الدعوة، يتم وضع علامة COMPLETED على GuardianInvitation ويتم إنشاء مورد Guardian.

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

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

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

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

المستويات

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

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

جافا

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(). هذه هي الطريقة الوحيدة لإزالة دعوة.

جافا

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(). لن يتم عرض سوى الدعوات التي تحمل الحالة PENDING بشكلٍ تلقائي. يمكن لمشرف النطاق أيضًا استرداد الدعوات التي تحمل الحالة COMPLETED من خلال تقديم مَعلمة states.

جافا

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

عرض الأوصياء النشطين

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

جافا

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

جافا

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()
السابق
إنشاء دعوات الدورات التدريبية وإدارتها
التالي
إنشاء مجموعات الطلاب وإدارتها