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

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

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

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

قد تتغير حالة GuardianInvitation أيضًا إلى 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
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 دعوة فقط. يمكن أيضًا لمشرف النطاق retrieving invitations in the COMPLETED state by providing a states parameter.

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