إدارة حقول المستخدمين المُخصَّصة

يمكنك تحديد حقول مخصَّصة للمستخدمين في نطاقك من خلال إضافة مخططات مستخدمين مخصّصة إلى النطاق. يمكنك استخدام هذه الحقول لتخزين معلومات مثل المشروعات التي يعمل عليها المستخدمون لديك أو مواقعهم الفعلية أو تاريخ تعيينهم أو أي شيء آخر يتناسب مع احتياجات عملك.

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

بعد تحديد المخطط، تعمل الحقول المخصّصة تمامًا مثل الحقول العادية. يمكنك ضبطها عند تحديث المستخدمين على نطاقك، وجلبهم باستخدام users.get وusers.list، وكذلك البحث عن حقول مخصّصة.

ضبط الحقول المخصصة في الملف الشخصي للمستخدم

لتعديل مخطط أو إنشائه، أنشِئ خاصية customSchemas وأضِفها إلى مورد المستخدم. داخل السمة customSchemas، يتم تجميع الحقول المخصّصة حسب المخطط بتنسيق JSON العادي:

"customSchemas": {
  "schema1": {
    "field1": "value1",
    "field2": [
      { "value": "value2a" },
      { "value": "value2b" },
      ...
    ],
    ...
  },
  "schema2": {
    "field3": "value3",
    ...
  },
  ...
}

يتم ضبط الحقول المخصّصة أحادية القيمة كأزواج بسيطة من المفاتيح والقيم، مثل "field1": "value1". يتم ضبط الحقول المخصّصة المتعدّدة القيم كصفائف من العناصر، مثل الحقول العادية المتعدّدة القيم في واجهة برمجة التطبيقات، مثل addresses وphones. تتوافق كائنات القيم هذه مع المفاتيح التالية:

المفاتيح
value	القيمة المطلوب تخزينها مطلوبة.
type	نوع القيمة، اختياري. القيم المتاحة: custom home other work
customType	نوع مخصّص للقيمة، اختياري. ويجب استخدام هذه السياسة عند ضبط type على custom.

إذا لم يتم تحديد حقل مُخصص في أي مخطط وقت التعديل، سيتم تركه كما هو. في حال عدم تحديد المخطّط نفسه في customFields في وقت التعديل، يتم ترك جميع الحقول المخصّصة في ذلك المخطط بدون تغيير. لحذف حقل مخصّص أو مخطط مخصّص من ملف شخصي، عليك ضبطه على null بشكل صريح:

"schema1": {
  "field1": null // deletes field1 from this profile.
}

طلب JSON

يؤدّي الطلب الوارد في المثال أدناه إلى تعديل المستخدم وتحديد قيم للمخطط المخصّص employmentData:

PATCH https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

{
  "customSchemas": {
    "employmentData": {
      "employeeNumber": "123456789",
      "jobFamily": "Engineering"
      "location": "Atlanta",
      "jobLevel": 8,
      "projects": [
        { "value": "GeneGnome" },
        { "value": "Panopticon", "type": "work" },
        { "value": "MegaGene", "type": "custom", "customType": "secret" }
      ]
    }
  }
}

قراءة الحقول المخصصة في الملف الشخصي للمستخدم

يمكنك استرجاع الحقول المخصّصة في الملف الشخصي للمستخدم من خلال ضبط المَعلمة projection في طلب users.get أو users.list على custom أو full.

البحث في الحقول المخصصة في الملف الشخصي للمستخدم

يمكنك البحث ضمن الحقول المخصّصة باستخدام المَعلمة query في طلب users.list. عليك طلب الحقل المخصّص باستخدام بنية schemaName.fieldName. مثال:

employmentData.projects:"GeneGnome"

لجميع الموظفين الذين يعملون في مشروع GeneGnome. سيعرض طلب البحث

employmentData.location="Atlanta" employmentData.jobLevel>=7

يعود لجميع الموظفين في أتلانتا أعلى من المستوى 7. لمزيد من المعلومات، يُرجى الاطّلاع على المستخدمون في "بحث Google".

إنشاء مخطط مستخدم مخصص

يمكن إضافة مخطط مستخدم مخصّص إلى جميع نطاقات حسابك على Google Workspace. لإنشاء مخطّط مستخدم مخصّص في نطاقاتك، استخدِم طلب POST التالي وضمِّن التفويض الموضّح في طلبات التفويض. بالنسبة إلى خصائص سلسلة طلب البحث، راجِع مرجع واجهة برمجة التطبيقات.

POST https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

تتطلب منك جميع طلبات الإنشاء إرسال المعلومات اللازمة لتنفيذ الطلب. إذا كنت تستخدم مكتبات العملاء، يمكنك تحويل كائنات البيانات من اللغة التي اخترتها إلى كائنات بتنسيق بيانات JSON.

طلب JSON

يعرض المثال التالي طلبًا لإنشاء مخطط مخصص. للحصول على القائمة الكاملة لخصائص الطلب والاستجابة، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات.

{
  "schemaName": "employmentData",
  "fields": [
    {
      "fieldName": "EmployeeNumber",
      "fieldType": "STRING",
      "multiValued": "false"
    },
    {
      "fieldName": "JobFamily",
      "fieldType": "STRING",
      "multiValued": "false"
    }
  ]
}

تعرض الاستجابة الناجحة رمز حالة HTTP 201 مع خصائص المخطط المخصَّص الجديد.

حدود المخططات المخصَّصة

• يبلغ الحدّ الأقصى لعدد المخططات المخصّصة المسموح بها في الحساب 100.
• يبلغ الحدّ الأقصى لعدد الحقول المخصّصة المسموح بها في الحساب 100 حقل.
• إنّ الحدّ الأقصى لعدد الأحرف المسموح به في الحقل string للحقل المخصّص أحادي القيمة هو 500 حرف. بالنسبة إلى الحقول المخصصة متعددة القيم، يعتمد عدد العناصر المسموح بها على حجم القيم المعينة. على سبيل المثال، يمكنك إضافة 150 قيمة لكل منها 100 حرف أو 50 قيمة لكل منها 500 حرف.
• الأحرف المسموح بها في المخططات المخصَّصة وأسماء الحقول هي أحرف أبجدية رقمية وشرطات سفلية (_) وواصلات (-).
• غير مسموح بتغيير نوع الحقل.
• يمكن جعل الحقل أحادي القيمة متعدد القيم، ولكن لا يُسمح بالعملية العكسية.
• لا يمكن إعادة تسمية المخططات أو الحقول المخصصة.

تعديل مخطط مستخدم مخصَّص

لتعديل مخطط مخصَّص، استخدِم طلب PUT التالي وضمِّن التفويض الموضّح في طلبات التفويض. ويمكن أن تشير السمة schemaKey إلى اسم المخطط أو المخطط الفريد id. للاطّلاع على خصائص الطلب والاستجابة، راجِع مرجع واجهة برمجة التطبيقات.

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

طلب JSON

في المثال أدناه، كان المخطط employmentData يحتوي على حقل JobFamily عند إنشائه. يجري الطلب تعديلاً لـ employmentData ليحتوي على حقل EmployeeNumber فقط:

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/schemas/employmentData

{
  "kind": "admin#directory#schema",
  "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
  "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
  "schemaName": "employmentData",
  "fields": [
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
      "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
      "fieldType": "STRING",
      "fieldName": "EmployeeNumber",
      "multiValued": "false"
    }
  ]
}

تتطلب منك جميع طلبات التحديث إرسال المعلومات اللازمة لتنفيذ الطلب.

تعرض الاستجابة الناجحة رمز حالة HTTP 200 إلى جانب مورد المخطط المعدَّل.

استرداد مخطط مستخدم مُخصص

لاسترداد مخطط مخصّص، استخدِم طلب GET التالي وضمِّن التفويض الموضّح في طلبات التفويض. ويمكن أن تشير السمة schemaKey إلى اسم المخطط أو المخطط الفريد id. للاطّلاع على خصائص الطلب والاستجابة، راجِع مرجع واجهة برمجة التطبيقات.

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

تعرض الاستجابة الناجحة رمز حالة HTTP 200 إلى جانب خصائص المخطط المخصّص.

{
  "kind": "admin#directory#schema",
  "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
  "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
  "schemaName": "employmentData",
  "fields": [
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
      "fieldType": "STRING",
      "fieldName": "EmployeeNumber"
    },
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
      "fieldType": "STRING",
      "fieldName": "JobFamily"
    }
  ]
}

استرداد جميع مخططات المستخدم المخصّصة

لاسترداد جميع المخططات المخصَّصة في الحساب نفسه، استخدِم طلب GET التالي وأدرِج التفويض الموضّح في طلبات التفويض.وبالنسبة إلى خصائص الطلب والاستجابة، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات.

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

تعرض الاستجابة الناجحة رمز حالة HTTP 200 إلى جانب المخططات المخصّصة للحساب.

{
  "kind": "admin#directory#schemas",
  "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/iJ1eWn5AKuR-xTdwH_2IBlvSSKo\"",
  "schemas": [
    {
      "kind": "admin#directory#schema",
      "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
      "schemaName": "employmentData",
      "fields": [
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
          "fieldType": "STRING",
          "fieldName": "EmployeeNumber"
        },
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
          "fieldType": "STRING",
          "fieldName": "JobFamily"
        }
      ]
    }
  ]
}