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

يمثّل 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():

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

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

عرض قائمة الأوصياء النشطين

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