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

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

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

هنگامی که یک طرحواره تعریف شد، فیلدهای سفارشی درست مانند فیلدهای استاندارد رفتار می کنند. می توانید آنها را هنگام به روز رسانی کاربران در دامنه خود تنظیم کنید، آنها را با 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

همه کارکنان آتلانتا را بالاتر از سطح شغلی 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 را به همراه ویژگی‌های طرح سفارشی جدید برمی‌گرداند.

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

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

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

برای به‌روزرسانی یک طرح سفارشی، از درخواست 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"
        }
      ]
    }
  ]
}