Zarządzanie niestandardowymi polami użytkownika

Możesz zdefiniować pola niestandardowe dla użytkowników w domenie, dodając do niej niestandardowe schematy użytkowników. W tych polach możesz przechowywać informacje takie jak projekty, nad którymi pracują użytkownicy, ich lokalizacje fizyczne, daty zatrudnienia lub inne dane, które odpowiadają potrzebom Twojej firmy.

Na początek utwórz co najmniej 1 schemat, aby zdefiniować pola niestandardowe, które są odpowiednie dla Twojej domeny. Możesz określić wiele atrybutów, takich jak nazwa pola, typ (ciąg znaków, wartość logiczna, liczba całkowita itp.), czy jest to pole z jedną czy wieloma wartościami oraz czy jego wartości są widoczne dla wszystkich użytkowników w Twojej domenie, czy tylko dla administratorów i powiązanego użytkownika.

Po zdefiniowaniu schematu pola niestandardowe działają tak samo jak pola standardowe. Możesz je ustawić podczas aktualizowania użytkowników w domenie, pobierać za pomocą users.get i users.list, a także wyszukiwać pola niestandardowe.

Ustawianie pól niestandardowych w profilu użytkownika

Aby zaktualizować lub utworzyć schemat, utwórz customSchemaswłaściwość i dodaj ją do zasobu użytkownika. W ramach właściwości customSchemas pola niestandardowe są grupowane według schematu w standardowym formacie JSON:

"customSchemas": {
  "schema1": {
    "field1": "value1",
    "field2": [
      { "value": "value2a" },
      { "value": "value2b" },
      ...
    ],
    ...
  },
  "schema2": {
    "field3": "value3",
    ...
  },
  ...
}

Pola niestandardowe o jednej wartości są ustawiane jako proste pary klucz-wartość, np. "field1": "value1". Pola niestandardowe o wielu wartościach są ustawiane jako tablice obiektów, podobnie jak standardowe pola o wielu wartościach w interfejsie API, takie jak addresses i phones. Te obiekty wartości obsługują następujące klucze:

Klucze
value Wartość do zapisania (wymagana).
type Typ wartości (opcjonalnie). Możliwe wartości:
  • custom
  • home
  • other
  • work
customType Niestandardowy typ wartości (opcjonalnie). Musi być używany, gdy atrybut type ma wartość custom.

Jeśli w momencie aktualizacji nie określisz pola niestandardowego w schemacie, pozostanie ono bez zmian. Jeśli w momencie aktualizacji w polu customFields nie zostanie określony schemat, wszystkie pola niestandardowe w tym schemacie pozostaną bez zmian. Aby usunąć z profilu pole niestandardowe lub schemat niestandardowy, musisz ustawić go na null:

"schema1": {
  "field1": null // deletes field1 from this profile.
}

Żądanie JSON

Wywołanie w przykładzie poniżej aktualizuje użytkownika i ustawia wartości w employmentData schemacie niestandardowym:

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

Odczytywanie pól niestandardowych w profilu użytkownika

Możesz pobrać pola niestandardowe w profilu użytkownika, ustawiając parametr projectionw żądaniu users.get lub users.list na custom lub full.

Wyszukiwanie pól niestandardowych w profilu użytkownika

Możesz wyszukiwać w polach niestandardowych za pomocą parametru query w żądaniu users.list. Pole niestandardowe możesz wysłać za pomocą składni schemaName.fieldName. Na przykład:

employmentData.projects:"GeneGnome"

zwraca wszystkich pracowników, którzy pracują nad projektem GeneGnome. Zapytanie

employmentData.location="Atlanta" employmentData.jobLevel>=7

zwraca wszystkich pracowników w Atlancie, którzy są na poziomie stanowiska powyżej 7. Więcej informacji znajdziesz w artykule Wyszukiwanie użytkowników.

Tworzenie niestandardowego schematu użytkownika

Niestandardowy schemat użytkownika można dodać do wszystkich domen na koncie Google Workspace. Aby utworzyć w swoich domenach niestandardowy schemat użytkownika, użyj tego żądaniaPOST i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. Informacje o właściwościach ciągu zapytania żądania znajdziesz w dokumentacji API.

POST https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

Wszystkie prośby o utworzenie wymagają przesłania informacji potrzebnych do ich realizacji. Jeśli używasz bibliotek klienta, przekształcają one obiekty danych z wybranego języka w sformatowane obiekty danych JSON.

Żądanie JSON

Poniższy przykład pokazuje żądanie utworzenia schematu niestandardowego. Pełną listę właściwości żądań i odpowiedzi znajdziesz w dokumentacji API.

{
  "schemaName": "employmentData",
  "fields": [
    {
      "fieldName": "EmployeeNumber",
      "fieldType": "STRING",
      "multiValued": "false"
    },
    {
      "fieldName": "JobFamily",
      "fieldType": "STRING",
      "multiValued": "false"
    }
  ]
}

Odpowiedź zakończona powodzeniem zwraca kod stanu HTTP 201 oraz właściwości nowego schematu niestandardowego.

Limity schematów niestandardowych

  • Maksymalna liczba dozwolonych schematów niestandardowych na koncie to 100.
  • Maksymalna liczba dozwolonych pól niestandardowych na koncie to 100.
  • Maksymalna liczba znaków dozwolonych w polu string w przypadku pola niestandardowego o pojedynczej wartości to 500. W przypadku pól niestandardowych z wieloma wartościami liczba dozwolonych elementów zależy od rozmiaru przypisanych wartości. Możesz na przykład dodać 150 wartości po 100 znaków każda lub 50 wartości po 500 znaków każda.
  • W schematach niestandardowych i nazwach pól dozwolone są znaki alfanumeryczne, podkreślenia (_) i łączniki (-).
  • Nie można zmienić typu pola.
  • Pole o jednej wartości można przekształcić w pole o wielu wartościach, ale operacja odwrotna jest niedozwolona.
  • Nie można zmienić nazwy schematów ani pól niestandardowych.

Aktualizowanie niestandardowego schematu użytkownika

Aby zaktualizować schemat niestandardowy, użyj poniższego żądania PUT i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. schemaKey może być nazwą schematu lub unikalnym identyfikatorem schematu id. Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

Żądanie JSON

W przykładzie poniżej schemat employmentData zawierał pole JobFamily w momencie utworzenia. Żądanie aktualizuje pole employmentData, aby zawierało tylko pole 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"
    }
  ]
}

W przypadku wszystkich próśb o aktualizację musisz przesłać informacje potrzebne do ich realizacji.

Odpowiedź zakończona powodzeniem zwraca kod stanu HTTP 200 i zaktualizowany zasób schematu.

Pobieranie niestandardowego schematu użytkownika

Aby pobrać schemat niestandardowy, użyj poniższego żądania GET i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. schemaKey może być nazwą schematu lub unikalnym identyfikatorem schematu id. Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

Odpowiedź zakończona powodzeniem zwraca kod stanu HTTP 200 wraz z właściwościami schematu niestandardowego.

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

Pobieranie wszystkich niestandardowych schematów użytkownika

Aby pobrać wszystkie schematy niestandardowe na tym samym koncie, użyj tego GETżądania i dołącz autoryzację opisaną w artykule Autoryzowanie żądań.Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

Pomyślna odpowiedź zwraca kod stanu HTTP 200 wraz ze schematami niestandardowymi konta.

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