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

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

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

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