ניהול של שדות משתמש בהתאמה אישית

אפשר להגדיר שדות מותאמים אישית למשתמשים בדומיין על ידי הוספת סכימות מותאמות אישית של משתמשים לדומיין. אפשר להשתמש בשדות האלה כדי לאחסן מידע כמו הפרויקטים שהמשתמשים עובדים עליהם, המיקומים הפיזיים שלהם, תאריכי ההעסקה שלהם או כל מידע אחר שמתאים לצרכים העסקיים שלכם.

בתור התחלה, צריך ליצור סכימה אחת או יותר כדי להגדיר את השדות המותאמים אישית שמתאימים לדומיין. ניתן לציין כמה מאפיינים, כמו שם השדה, הסוג (מחרוזת, בוליאני, מספר שלם וכו'), בין שהוא יחיד או מרובה ערכים, ואם לכל משתמש בדומיין ניתן לראות את הערכים שלו, או רק לאדמינים ולמשתמש המשויך.

אחרי שמגדירים סכימה, השדות בהתאמה אישית פועלים בדיוק כמו שדות רגילים. אפשר להגדיר אותם כשמעדכנים משתמשים בדומיין, לאחזר אותם באמצעות 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 הבאה ולכלול את ההרשאות שמתוארות בקטע Authorize requests. למידע על המאפיינים של מחרוזת השאילתה של הבקשה, קראו את חומר העזר בנושא 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 הבאה וכוללים את ההרשאה שמתוארת בקטע Authorize requests. השדה 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 הבאה וכוללים את ההרשאה שמתוארת בקטע Authorize requests. השדה 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 הבאה וכוללים את ההרשאה שמתוארת בקטע Authorize requests.למידע על מאפייני הבקשות והתגובה, אפשר לעיין בחומר העזר בנושא 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"
        }
      ]
    }
  ]
}