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

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

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

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

طلب 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 Workspace. لإنشاء مخطط مستخدم مخصّص في نطاقاتك، استخدِم طلب POST التالي وأضِف التفويض الموضّح في طلبات التفويض. للاطّلاع على سمات سلسلة طلب البحث، يُرجى مراجعة مرجع واجهة برمجة التطبيقات.

POST https://admin.googleapis.com/admin/directory/v1/customer/<var>my_customer or customerId</var>/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"
        },
        {
          &quot;kind": "admin#directory#schema#fieldspec",
          "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
          "fieldType": "STRING",
          "fieldName": "JobFamily"
        }
      ]
    }
  ]
}