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

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

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

بعد تحديد المخطط، تعمل الحقول المخصّصة على غرار الحقول العادية تمامًا. يمكنك ضبطها عند تعديل بيانات المستخدمين على نطاقك، وجلبهم باستخدام 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"
        }
      ]
    }
  ]
}