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

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

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

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