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

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

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

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

{
  "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/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"
        }
      ]
    }
  ]
}