Zarządzanie niestandardowymi polami użytkowników

Możesz definiować pola niestandardowe dla użytkowników w swojej domenie, dodając do niej niestandardowe schematy użytkowników. W tych polach możesz przechowywać takie informacje jak projekty, nad którymi pracują Twoi użytkownicy, ich lokalizacje fizyczne, data zatrudnienia i inne informacje, które odpowiadają Twoim potrzebom biznesowym.

Na początek utwórz co najmniej jeden schemat, aby zdefiniować pola niestandardowe 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 jedno- czy wielowartościowy oraz czy jego wartości są widoczne dla każdego użytkownika w 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 kont użytkowników w domenie, pobierać je 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 właściwość customSchemas i dodaj ją do zasobu użytkownika. We właściwości customSchemas pola niestandardowe są pogrupowane według schematu w standardowym formacie JSON:

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

Jednowartościowe pola niestandardowe są ustawione jako proste pary klucz-wartość, np. "field1": "value1". Wielowartościowe pola niestandardowe są ustawiane jako tablice obiektów, tak jak w interfejsie API standardowe pola wielowartościowe, np. addresses i phones. Obiekty wartości obsługują następujące klucze:

Klucze
value Wymagana wartość do zapisania.
type Opcjonalny typ wartości. Możliwe wartości:
  • custom
  • home
  • other
  • work
customType Niestandardowy typ wartości, opcjonalny. Musi być używana, gdy zasada type ma wartość custom.

Jeśli pole niestandardowe w schemacie nie jest określone w momencie aktualizacji, pozostaje bez zmian. Jeśli sam schemat nie jest określony w dyrektywie customFields w czasie aktualizacji, wszystkie pola niestandardowe w tym schemacie pozostaną bez zmian. Aby usunąć z profilu pole niestandardowe lub schemat niestandardowy, musisz bezpośrednio ustawić w tym profilu wartość null:

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

Żądanie JSON

Wywołanie w poniższym przykładzie aktualizuje konto użytkownika i ustawia wartości niestandardowego schematu 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 pobierać, ustawiając parametr projection w żą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. Żądasz pola niestandardowego ze składnią schemaName.fieldName. Na przykład:

employmentData.projects:"GeneGnome"

zwraca wszystkich pracowników pracujących nad projektem GeneGnome. Zapytanie

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

zwraca wszystkim pracownikom w Atlancie poziom 7. Więcej informacji znajdziesz w artykule Użytkownicy wyszukiwania.

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 poniższego żądania POST i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. Właściwości ciągu zapytania żądania znajdziesz w dokumentacji interfejsu API.

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

Wszystkie prośby o utworzenie wymagają przesłania informacji niezbędnych do spełnienia żądania. Jeśli używasz bibliotek klienta, konwertują one obiekty danych z wybranego języka na obiekty w formacie danych JSON.

Żądanie JSON

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

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

Pomyślna odpowiedź zwraca kod stanu HTTP 201 i właściwości nowego schematu niestandardowego.

Limity dotyczące schematu niestandardowego

  • Maksymalna liczba schematów niestandardowych dozwolonych na koncie to 100.
  • Maksymalna dozwolona liczba pól niestandardowych na koncie to 100.
  • Maksymalna dozwolona liczba znaków w polu string w przypadku jednowartościowego pola niestandardowego to 500. W przypadku wielowartościowych pól niestandardowych liczba dozwolonych elementów zależy od rozmiaru przypisanych wartości. Możesz np. dodać 150 wartości po 100 znaków lub 50 wartości po 500 znaków każda.
  • W niestandardowych schematach i nazwach pól dozwolone są znaki alfanumeryczne, podkreślenia (_) i łączniki (-).
  • Zmiana typu pola jest niedozwolona.
  • Pole jednowartościowe może być wielowartościowe, ale operacja odwrotna jest niedozwolona.
  • Nie można zmieniać nazw niestandardowych schematów ani pól.

Aktualizowanie niestandardowego schematu użytkownika

Aby zaktualizować niestandardowy schemat, użyj poniższego żądania PUT i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. Pole schemaKey może być nazwą schematu lub unikalnym schematem id. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji interfejsu 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 podczas tworzenia zawierał pole JobFamily. Prośba aktualizuje 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"
    }
  ]
}

W przypadku każdej prośby o aktualizację musisz przesłać informacje niezbędne do jej spełnienia.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 i zaktualizowany zasób schematu.

Pobieranie niestandardowego schematu użytkownika

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

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

Pomyślna odpowiedź zwraca kod stanu HTTP 200 i 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"
    }
  ]
}

Pobierz wszystkie niestandardowe schematy użytkownika

Aby pobrać wszystkie schematy niestandardowe z tego samego konta, użyj poniższego żądania GET i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań.Właściwości żądania i odpowiedzi znajdziesz w dokumentacji interfejsu API.

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

Pomyślna odpowiedź zwraca kod stanu HTTP 200 oraz niestandardowe schematy 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"
        }
      ]
    }
  ]
}