Zarządzanie niestandardowymi polami użytkowników

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, data zatrudnienia lub inne informacje odpowiadające potrzebom Twojej firmy.

Na początek utwórz co najmniej jeden schemat, aby zdefiniować pola niestandardowe, które mają sens w przypadku Twojej domeny. Możesz określić kilka atrybutów, takich jak nazwa pola, typ (string, boolean, integer itp.), czy pole ma jedną czy wiele wartości oraz czy jego wartości są widoczne dla dowolnego użytkownika 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, pobrać je za pomocą users.get i users.list oraz wyszukiwać pola niestandardowe.

Konfigurowanie pól niestandardowych w profilu użytkownika

Aby zaktualizować lub utworzyć schemat, utwórz właściwość customSchemasi dodaj ją do zasobu użytkownika. W usłudze 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 pojedynczej wartości są ustawiane jako proste pary klucz-wartość, np. "field1": "value1". Wielowartościowe pola niestandardowe są ustawiane jako tablice obiektów, podobnie jak standardowe pola wielowartościowe w interfejsie API, np. addresses i phones. Te obiekty wartości obsługują te 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 type ma wartość custom.

Jeśli w schemacie nie zostanie określone pole niestandardowe, nie zostanie ono zmienione. Jeśli w polu customFields nie ma określonego schematu w momencie aktualizacji, wszystkie pola niestandardowe w tym schemacie pozostają bez zmian. Aby usunąć z profilu niestandardowe pole lub niestandardowy schemat, musisz je wyraźnie ustawić na null:

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

Żądanie JSON

Wywołanie w przykładie poniżej aktualizuje użytkownika i ustala wartości dla schematu niestandardowego employmentData:

PATCH https://admin.googleapis.com/admin/directory/v1/users/[email protected]

{
  "customSchemas": {
    "employmentData": {
      "employeeNumber": "123456789",
      "jobFamily": "Engineering"
      "location": "Atlanta",
      "jobLevel": 8,
      "projects": [
        { "value": "GeneGnome" },
        { "value": "Panopticon", "type": "work" },
        { "value": "MegaGene", "type": "custom", "customType": "secret" }
      ]
    }
  }
}

odczytywać pól niestandardowych w profilu użytkownika.

Pola niestandardowe w profilu użytkownika możesz pobrać, ustawiając parametr projection w żądaniu users.get lub users.list na custom lub full.

Wyszukiwanie pól niestandardowych w profilu użytkownika

W polach niestandardowych możesz wyszukiwać za pomocą parametru query w żądaniu users.list. Pole niestandardowe możesz zapytać 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 o poziomie stanowiska wyższym niż 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 konta Google Workspace. Aby utworzyć niestandardowy schemat użytkownika w swoich domenach, użyj tego żądania POST i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. Więcej informacji 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

W przypadku wszystkich żądań tworzenia musisz przesłać informacje potrzebne do spełnienia żądania. Jeśli używasz bibliotek klienta, konwertują one obiekty danych z wybranego języka na obiekty danych w formacie JSON.

Żądanie JSON

Ten przykładowy przypadek przedstawia żądanie utworzenia niestandardowego schematu. 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"
    }
  ]
}

Pomyślna odpowiedź zwraca kod stanu HTTP 201 wraz z właściwościami nowego schematu niestandardowego.

Ograniczenia schematów niestandardowych

  • Maksymalna dozwolona liczba schematów niestandardowych na koncie to 100.
  • Maksymalna dozwolona liczba pól niestandardowych na koncie to 100.
  • Maksymalna dozwolona liczba znaków w polu string w przypadku pola niestandardowego z jedną wartością to 500. W przypadku pól niestandardowych z wieloma wartościami dozwolona liczba elementów zależy od rozmiaru przypisanych wartości. Możesz na przykład dodać 150 wartości po 100 znaków lub 50 wartości po 500 znaków.
  • W nazwach niestandardowych schematów i pól można używać znaków alfanumerycznych, znaków podkreślenia (_) i łączników (-).
  • Zmiana typu pola jest niedozwolona.
  • Z pola o jednej wartości można zrobić pole o wielu wartościach, ale operacja odwrotna jest niedozwolona.
  • Nie można zmieniać nazw schematów ani pól niestandardowych.

Aktualizowanie niestandardowego schematu użytkownika

Aby zaktualizować niestandardowy schemat, użyj poniższego żądania PUT i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. Wartością parametru schemaKey może być nazwa schematu lub niepowtarzalny schemat id. Właściwości żą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ł pierwotnie utworzone pole JobFamily. Prośba aktualizuje tabelę employmentData tak, aby zawierała 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"
    }
  ]
}

Wszystkie prośby o aktualizację wymagają przesłania informacji potrzebnych do spełnienia prośby.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 wraz z zaktualizowanym zasobem schematu.

Pobieranie niestandardowego schematu użytkownika

Aby pobrać niestandardowy schemat, użyj poniższego żądania GET i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. Wartością parametru schemaKey może być nazwa schematu lub niepowtarzalny schemat id. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API.

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

Pomyślna odpowiedź 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żytkowników

Aby pobrać wszystkie niestandardowe schematy na tym samym koncie, użyj tego GETżądania i dołącz autoryzację opisaną w artykule Autoryzowanie żądań.Właściwości żądania i odpowiedzi znajdziesz w dokumentacji Referencje 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"
        }
      ]
    }
  ]
}