Benutzerdefinierte Nutzerfelder verwalten

Sie können benutzerdefinierte Felder für Nutzer in Ihrer Domain definieren, indem Sie der Domain benutzerdefinierte Nutzerschemas hinzufügen. Sie können diese Felder verwenden, um Informationen wie die Projekte, an denen Ihre Nutzer arbeiten, ihre physischen Standorte, ihr Einstellungsdatum oder andere Informationen zu speichern, die Ihren Geschäftsanforderungen entsprechen.

Erstellen Sie zuerst ein oder mehrere Schemas, um die für Ihre Domain sinnvollen benutzerdefinierten Felder zu definieren. Sie können eine Reihe von Attributen angeben, z. B. den Namen des Felds, den Typ (String, boolescher Wert, Ganzzahl usw.), ob das Feld ein- oder mehrwertig ist und ob seine Werte für jeden Nutzer in Ihrer Domain oder nur für Administratoren und den zugehörigen Nutzer sichtbar sind.

Nachdem ein Schema definiert wurde, verhalten sich die benutzerdefinierten Felder wie Standardfelder. Sie können sie festlegen, wenn Sie Nutzer in Ihrer Domain aktualisieren, sie mit users.get und users.list abrufen und auch nach benutzerdefinierten Feldern suchen.

Hinweis: Benutzerdefinierte Felder können auch von der Cloud Identity Groups API verwendet werden, um dynamische Gruppenabfragen zum Definieren der Gruppenmitgliedschaft zu erstellen. Weitere Informationen finden Sie unter Mitgliedschaftsabfrage formulieren und testen.

Warnung: Verwenden Sie diese Funktion nicht zum Speichern vertraulicher personenidentifizierbarer Informationen wie Anmeldedaten für Konten, Behörden-Identifikationsnummern, Karteninhaberdaten, Bankkontodaten, Gesundheitsinformationen oder vertrauliche Hintergrundinformationen.

Benutzerdefinierte Felder in einem Nutzerprofil festlegen

Wenn Sie ein Schema aktualisieren oder erstellen möchten, erstellen Sie ein customSchemas-Attribut und fügen Sie es der Nutzerressource hinzu. Im Attribut customSchemas sind die benutzerdefinierten Felder nach Schema im JSON-Standardformat gruppiert:

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

Hinweis: Jeder schemaName muss innerhalb eines Kunden eindeutig sein. Die Wiederverwendung eines Namens führt zum Fehler 409: Entity already exists.

Einwertige benutzerdefinierte Felder werden als einfache Schlüssel/Wert-Paare wie "field1": "value1" festgelegt. Mehrwertige benutzerdefinierte Felder werden als Objektarrays festgelegt, wie die standardmäßigen mehrwertigen Felder in der API, z. B. addresses und phones. Diese Wertobjekte unterstützen die folgenden Schlüssel:

Schlüssel
value	Der zu speichernde Wert (erforderlich).
type	Typ des Werts, optional. Folgende Werte sind möglich: custom home other work
customType	Benutzerdefinierter Typ des Werts (optional). Muss verwendet werden, wenn type auf custom gesetzt ist.

Wenn ein benutzerdefiniertes Feld in einem Schema bei der Aktualisierung nicht angegeben wurde, bleibt es unverändert. Wenn ein Schema selbst bei der Aktualisierung nicht in customFields angegeben wird, bleiben alle benutzerdefinierten Felder in diesem Schema unverändert. Wenn Sie ein benutzerdefiniertes Feld oder ein benutzerdefiniertes Schema aus einem Profil löschen möchten, müssen Sie es explizit auf null setzen:

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

JSON-Anfrage

Mit dem Aufruf im folgenden Beispiel wird ein Nutzer aktualisiert und Werte für das benutzerdefinierte Schema employmentData festgelegt:

PATCH https://admin.googleapis.com/admin/directory/v1/users/[e-mail]

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

Benutzerdefinierte Felder in einem Nutzerprofil lesen

Sie können benutzerdefinierte Felder in einem Nutzerprofil abrufen. Dazu setzen Sie den Parameter projection in einer users.get- oder users.list-Anfrage auf custom oder full.

Benutzerdefinierte Felder in einem Nutzerprofil suchen

Mit dem Parameter query in einer users.list-Anfrage können Sie in benutzerdefinierten Feldern suchen. Sie fordern das benutzerdefinierte Feld mit einer schemaName.fieldName-Syntax an. Beispiel:

employmentData.projects:"GeneGnome"

gibt alle Mitarbeitenden zurück, die am Projekt GeneGnome arbeiten. Die Anfrage

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

gibt alle Mitarbeitenden in Atlanta über Jobebene 7 zurück. Weitere Informationen finden Sie unter Nutzer suchen.

Benutzerdefiniertes Nutzerschema erstellen

Ein benutzerdefiniertes Nutzerschema kann allen Domains Ihres Google Workspace-Kontos hinzugefügt werden. Verwenden Sie die folgende POST-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein, um ein benutzerdefiniertes Nutzerschema in Ihren Domains zu erstellen. Informationen zu den Attributen des Anfrageabfragestrings finden Sie in der API-Referenz.

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

Bei allen Erstellungsanfragen müssen Sie die zur Ausführung der Anfrage erforderlichen Informationen senden. Wenn Sie Clientbibliotheken verwenden, werden die Datenobjekte aus der ausgewählten Sprache in JSON-Datenformate konvertiert.

JSON-Anfrage

Das folgende Beispiel zeigt eine Anfrage zum Erstellen eines benutzerdefinierten Schemas. Eine vollständige Liste der Anfrage- und Antwortattribute finden Sie in der API-Referenz.

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

Bei einer erfolgreichen Antwort werden ein HTTP 201-Statuscode zusammen mit den Attributen für das neue benutzerdefinierte Schema zurückgegeben.

Benutzerdefinierte Schemalimits

• In einem Konto sind maximal 100 benutzerdefinierte Schemas zulässig.
• In einem Konto sind maximal 100 benutzerdefinierte Felder zulässig.
• Im Feld string für ein einwertiges benutzerdefiniertes Feld sind maximal 500 Zeichen zulässig. Bei mehrwertigen benutzerdefinierten Feldern hängt die Anzahl der zulässigen Elemente von der Größe der zugewiesenen Werte ab. Sie können beispielsweise 150 Werte mit jeweils 100 Zeichen oder 50 Werte mit je 500 Zeichen hinzufügen.
• Die in benutzerdefinierten Schemas und Feldnamen zulässigen Zeichen sind alphanumerische Zeichen, Unterstriche (_) und Bindestriche (-).
• Das Ändern des Feldtyps ist nicht zulässig.
• Ein einwertiges Feld kann mehrwertig gemacht werden, der umgekehrte Vorgang ist jedoch nicht zulässig.
• Benutzerdefinierte Schemas oder Felder können nicht umbenannt werden.

Benutzerdefiniertes Nutzerschema aktualisieren

Verwenden Sie zum Aktualisieren eines benutzerdefinierten Schemas die folgende PUT-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein. Die schemaKey kann der Schemaname oder die eindeutige Schema-id sein. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz.

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

Hinweis: Die API unterstützt auch die Patch-Semantik.

JSON-Anfrage

Im folgenden Beispiel enthielt das Schema employmentData bei seiner Erstellung ein JobFamily-Feld. Die Anfrage aktualisiert employmentData so, dass er nur ein EmployeeNumber-Feld enthält:

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

Bei allen Aktualisierungsanfragen müssen Sie die zur Ausführung der Anfrage erforderlichen Informationen einreichen.

Bei einer erfolgreichen Antwort werden ein HTTP 200-Statuscode zusammen mit der aktualisierten Schemaressource zurückgegeben.

Benutzerdefiniertes Nutzerschema abrufen

Verwenden Sie die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein, um ein benutzerdefiniertes Schema abzurufen. Die schemaKey kann der Schemaname oder die eindeutige Schema-id sein. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz.

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

Bei einer erfolgreichen Antwort werden ein HTTP 200-Statuscode zusammen mit den Attributen für das benutzerdefinierte Schema zurückgegeben.

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

Alle benutzerdefinierten Nutzerschemas abrufen

Verwenden Sie die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein, um alle benutzerdefinierten Schemas im selben Konto abzurufen.Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz.

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

Bei einer erfolgreichen Antwort werden ein HTTP 200-Statuscode zusammen mit den benutzerdefinierten Schemas für das Konto zurückgegeben.

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