Zarządzanie niestandardowymi polami użytkownika

Możesz zdefiniować pola niestandardowe dla użytkowników w swojej domenie, dodając do niej niestandardowe schematy użytkowników. Za pomocą tych pól możesz przechowywać informacje takie jak projekty, nad którymi pracują użytkownicy, ich lokalizacje, daty zatrudnienia lub inne dane, które są przydatne w Twojej firmie.

Na początek utwórz co najmniej 1 schemat aby zdefiniować pola niestandardowe, które są odpowiednie dla Twojej domeny. Możesz określić liczbę 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 mogą być wyświetlane przez wszystkich użytkowników w Twojej domenie, czy tylko przez administratorów i powiązanego użytkownika.

Po zdefiniowaniu schematu pola niestandardowe działają tak samo jak pola standardowe. Możesz je ustawiać podczas aktualizowania użytkowników w swojej domenie, pobierać za pomocą metod 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 obrębie 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 z jedną wartością są ustawiane jako proste pary klucz-wartość, np. "field1": "value1". Pola niestandardowe z wieloma wartościami są ustawiane jako tablice obiektów, podobnie jak standardowe pola z wieloma wartościami w interfejsie API, takie jak addresses i phones. Te obiekty wartości obsługują te klucze:

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

Jeśli pole niestandardowe w schemacie nie zostanie określone w czasie aktualizacji, pozostanie bez zmian. Jeśli sam schemat nie zostanie określony w customFields w czasie aktualizacji, wszystkie pola niestandardowe w tym schemacie pozostaną bez zmian. Aby usunąć pole niestandardowe lub schemat niestandardowy z profilu, musisz wyraźnie ustawić jego wartość na null:

"schema1": {
  "field1": null
}

Żądanie JSON

Wywołanie w poniższym przykładzie aktualizuje użytkownika i ustawia wartości dla schematu niestandardowego 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" }
      ]
    }
  }
}

Odczytywanie pól niestandardowych w profilu użytkownika

Pola niestandardowe w profilu użytkownika możesz pobrać, ustawiając projection parametr w 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 wyszukać 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 mają stanowisko powyżej poziomu 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ć niestandardowy schemat użytkownika w swoich domenach, użyj poniższego POST żądania 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/<var>my_customer or customerId</var>/schemas

Wszystkie żądania tworzenia wymagają przesłania informacji potrzebnych do ich realizacji. Jeśli używasz bibliotek klienta, przekształcają one obiekty danych z wybranego języka na obiekty danych w formacie JSON.

Żądanie JSON

Ten przykład pokazuje żądanie utworzenia schematu niestandardowego. Pełną listę właściwości żądania 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, oraz właściwości nowego schematu niestandardowego.

Limity schematów niestandardowych

  • Maksymalna liczba schematów niestandardowych dozwolonych na koncie to 100.
  • Maksymalna liczba pól niestandardowych dozwolonych na koncie to 100.
  • Maksymalna liczba znaków dozwolonych w polu string dla pola niestandardowego z jedną 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.
  • Znaki dozwolone w schematach niestandardowych i nazwach pól to znaki alfanumeryczne, podkreślenia (_) i łączniki (-).
  • Zmiana typu pola jest niedozwolona.
  • Pole z jedną wartością można przekształcić w pole z wieloma wartościami, 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ń”. Parametr schemaKey może być nazwą schematu lub jego unikalnym identyfikatorem id. Informacje o właściwościach żądania i odpowiedzi znajdziesz w dokumentacji API.

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

Żądanie JSON

W poniższym przykładzie schemat employmentData zawierał pole JobFamily w momencie jego utworzenia. Żądanie aktualizuje schemat employmentData, aby zawierał 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 żądania aktualizacji wymagają przesłania informacji potrzebnych do ich realizacji.

Pomyślna odpowiedź zwraca kod stanu HTTP 200, oraz 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 artykule „Autoryzowanie żądań”. Parametr schemaKey może być nazwą schematu lub jego unikalnym identyfikatorem id. Informacje o właściwościach żądania 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, oraz właściwości 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 poniższego GET żądania i dołącz autoryzację opisaną w artykule „Autoryzowanie żądań”.Informacje o właściwościach żądania 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, oraz schematy niestandardowe dla 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"
        },
        {
          &quot;kind": "admin#directory#schema#fieldspec",
          "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
          "fieldType": "STRING",
          "fieldName": "JobFamily"
        }
      ]
    }
  ]
}