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

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

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

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

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

אחזור של כל סכימות המשתמשים המותאמות אישית

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