مدیریت فیلدهای کاربر سفارشی

شما می‌توانید با اضافه کردن طرحواره‌های کاربری سفارشی به دامنه، فیلدهای سفارشی برای کاربران دامنه خود تعریف کنید. می‌توانید از این فیلدها برای ذخیره اطلاعاتی مانند پروژه‌هایی که کاربران روی آنها کار می‌کنند، مکان‌های فیزیکی آنها، تاریخ استخدام آنها یا هر چیز دیگری که متناسب با نیازهای تجاری شما باشد، استفاده کنید.

برای شروع، یک یا چند طرحواره (schema) ایجاد کنید تا فیلدهای سفارشی مناسب برای دامنه خود را تعریف کنید. می‌توانید تعدادی ویژگی مانند نام فیلد، نوع (رشته‌ای، بولی، صحیح و غیره)، تک مقداری یا چند مقداری بودن آن و اینکه آیا مقادیر آن توسط هر کاربری در دامنه شما قابل مشاهده است یا فقط مدیران و کاربر مرتبط، را مشخص کنید.

پس از تعریف یک طرحواره، فیلدهای سفارشی درست مانند فیلدهای استاندارد رفتار می‌کنند. می‌توانید هنگام به‌روزرسانی کاربران در دامنه خود ، آنها را تنظیم کنید، آنها را با users.get و users.list دریافت کنید و همچنین فیلدهای سفارشی را جستجو کنید .

تنظیم فیلدهای سفارشی در پروفایل کاربر

برای به‌روزرسانی یا ایجاد یک طرحواره، یک ویژگی customSchemas ایجاد کنید و آن را به منبع کاربر اضافه کنید. درون ویژگی customSchemas ، فیلدهای سفارشی بر اساس طرحواره در قالب استاندارد JSON گروه‌بندی می‌شوند:

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

فیلدهای سفارشی تک مقداری به صورت جفت‌های ساده‌ی کلید-مقدار، مانند "field1": "value1" تنظیم می‌شوند. فیلدهای سفارشی چند مقداری به صورت آرایه‌هایی از اشیاء، مانند فیلدهای چند مقداری استاندارد در API مانند 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

همه کارمندان در آتلانتا را که سطح شغلی آنها بالاتر از ۷ است، برمی‌گرداند. برای اطلاعات بیشتر، به جستجوی کاربران مراجعه کنید.

ایجاد یک طرحواره کاربری سفارشی

یک طرحواره کاربری سفارشی می‌تواند به تمام دامنه‌های حساب Google Workspace شما اضافه شود. برای ایجاد یک طرحواره کاربری سفارشی در دامنه‌های خود، از درخواست POST زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را وارد کنید. برای ویژگی‌های رشته پرس و جوی درخواست، به مرجع API مراجعه کنید.

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

همه درخواست‌های ایجاد، شما را ملزم به ارسال اطلاعات مورد نیاز برای انجام درخواست می‌کنند. اگر از کتابخانه‌های کلاینت استفاده می‌کنید، آن‌ها اشیاء داده را از زبان انتخابی شما به اشیاء با فرمت داده JSON تبدیل می‌کنند.

درخواست JSON

نمونه زیر درخواستی برای ایجاد یک طرحواره سفارشی را نشان می‌دهد. برای لیست کامل ویژگی‌های درخواست و پاسخ، به مرجع API مراجعه کنید.

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

یک پاسخ موفقیت‌آمیز، کد وضعیت HTTP 201 را به همراه ویژگی‌های طرحواره سفارشی جدید برمی‌گرداند.

محدودیت‌های طرحواره سفارشی

  • حداکثر تعداد طرحواره‌های سفارشی مجاز در یک حساب کاربری ۱۰۰ عدد است.
  • حداکثر تعداد فیلدهای سفارشی مجاز در یک حساب کاربری ۱۰۰ است.
  • حداکثر تعداد کاراکترهای مجاز در یک فیلد string برای یک فیلد سفارشی تک مقداری، ۵۰۰ کاراکتر است. برای فیلدهای سفارشی چند مقداری، تعداد عناصر مجاز به اندازه مقادیر اختصاص داده شده بستگی دارد. به عنوان مثال، می‌توانید ۱۵۰ مقدار ۱۰۰ کاراکتری یا ۵۰ مقدار ۵۰۰ کاراکتری اضافه کنید.
  • کاراکترهای مجاز در طرحواره‌های سفارشی و نام فیلدها، کاراکترهای الفبایی-عددی، زیرخط ( _ ) و خط فاصله ( - ) هستند.
  • تغییر نوع فیلد مجاز نیست.
  • یک فیلد تک مقداری را می‌توان چند مقداری کرد، اما عملیات معکوس مجاز نیست.
  • تغییر نام طرحواره‌ها یا فیلدهای سفارشی امکان‌پذیر نیست.

به‌روزرسانی طرحواره کاربری سفارشی

برای به‌روزرسانی یک طرحواره سفارشی، از درخواست PUT زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را وارد کنید. schemaKey می‌تواند نام طرحواره یا id منحصر به فرد طرحواره باشد. برای ویژگی‌های درخواست و پاسخ، به مرجع API مراجعه کنید.

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 منحصر به فرد طرحواره باشد. برای ویژگی‌های درخواست و پاسخ، به مرجع API مراجعه کنید.

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 زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را وارد کنید. برای ویژگی‌های درخواست و پاسخ، به مرجع API مراجعه کنید. 

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