Benutzerdefinierte Nutzerfelder verwalten

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

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 zu speichern, z. B. die Projekte, an denen Ihre Nutzer arbeiten, ihren physischen Standort, ihr Einstellungsdatum oder andere beliebige Zwecke, die Ihren geschäftlichen Anforderungen entsprechen.

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

Sobald ein Schema definiert ist, verhalten sich die benutzerdefinierten Felder wie Standardfelder. Sie können sie beim Aktualisieren von Nutzern in Ihrer Domain festlegen, sie mit users.get und users.list abrufen und auch nach benutzerdefinierten Feldern suchen.

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 werden die benutzerdefinierten Felder nach Schema im Standard-JSON-Format gruppiert:

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

Benutzerdefinierte Felder mit einem Wert werden als einfache Schlüssel/Wert-Paare wie "field1": "value1" festgelegt. Benutzerdefinierte Felder mit mehreren Werten werden als Arrays von Objekten festgelegt, wie in den standardmäßigen Feldern mit mehreren Werten in der API, z. B. addresses und phones. Diese Wertobjekte unterstützen die folgenden Schlüssel:

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

Wenn ein benutzerdefiniertes Feld in einem Schema zum Zeitpunkt der Aktualisierung nicht angegeben ist, bleibt es unverändert. Wenn ein Schema zum Zeitpunkt der Aktualisierung in customFields nicht angegeben ist, 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 festlegen:

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

JSON-Anfrage

Durch den Aufruf im Beispiel unten wird ein Nutzer aktualisiert und ein Wert für das benutzerdefinierte employmentData-Schema festgelegt:

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

Benutzerdefinierte Felder in einem Nutzerprofil lesen

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

Benutzerdefinierte Felder in einem Nutzerprofil suchen

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

employmentData.projects:"GeneGnome"

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

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

gibt alle Mitarbeiter in Atlanta zurück, die älter als Joblevel 7 sind. 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 zum Erstellen eines benutzerdefinierten Nutzerschemas in Ihren Domains die folgende POST-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein. Informationen zu den Eigenschaften 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 Informationen angeben, die zur Ausführung der Anfrage erforderlich sind. Wenn Sie Clientbibliotheken verwenden, konvertieren sie die Datenobjekte aus der ausgewählten Sprache in JSON-Datenobjekte.

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

Eine erfolgreiche Antwort gibt einen HTTP 201-Statuscode zusammen mit den Attributen für das neue benutzerdefinierte Schema zurück.

Limits für benutzerdefinierte Schemas

  • In einem Konto sind maximal 100 benutzerdefinierte Schemas zulässig.
  • In einem Konto sind maximal 100 benutzerdefinierte Felder zulässig.
  • Die maximale Anzahl von Zeichen, die in einem string-Feld für ein benutzerdefiniertes benutzerdefiniertes Feld zulässig ist, beträgt 500. Bei benutzerdefinierten Feldern mit mehreren Werten 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 jeweils 500 Zeichen hinzufügen.
  • In benutzerdefinierten Schemas und Feldnamen sind folgende Zeichen zulässig: alphanumerische Zeichen, Unterstriche (_) und Bindestriche (-).
  • Der Feldtyp darf nicht geändert werden.
  • Ein einwertiges Feld kann in ein mehrwertiges Feld umgewandelt werden. Der inverse 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. schemaKey kann der Schemaname oder das 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

JSON-Anfrage

Im folgenden Beispiel enthielt das Schema employmentData bei seiner Erstellung das Feld JobFamily. Die Anfrage aktualisiert employmentData so, dass sie nur das Feld EmployeeNumber 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 Informationen angeben, die zur Ausführung der Anfrage erforderlich sind.

Eine erfolgreiche Antwort gibt einen HTTP 200-Statuscode zusammen mit der aktualisierten Schemaressource zurück.

Benutzerdefiniertes Nutzerschema abrufen

Verwenden Sie zum Abrufen eines benutzerdefinierten Schemas die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein. schemaKey kann der Schemaname oder das 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

Eine erfolgreiche Antwort gibt einen HTTP 200-Statuscode zusammen mit den Attributen für das benutzerdefinierte Schema zurück.

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

Wenn Sie alle benutzerdefinierten Schemas im selben Konto abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein.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

Eine erfolgreiche Antwort gibt einen HTTP 200-Statuscode zusammen mit den benutzerdefinierten Schemas für das Konto zurück.

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