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

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

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

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