تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

على الرغم من أنّ حالة الدعوة هي PENDING، قد يقبل المستخدم الدعوة، ما يؤدي إلى إنشاء مورد "الوصي" وتمييز "دعوة الوصي" بالحالة COMPLETED. قد تصبح الدعوة أيضًا 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.

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

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

لغة Java

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

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

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

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

لغة Java

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

العرض على 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='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

العرض على 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='student@mydomain.edu',
                                        guardianId='guardian@gmail.com').execute()