Benutzerdefinierte Nutzerfelder verwalten

Sie können benutzerdefinierte Felder für Nutzer in Ihrer Domain definieren, indem Sie der Domain benutzerdefinierte Nutzerschemas hinzufügen. In diesen Feldern können Sie Informationen wie die Projekte, an denen Ihre Nutzer arbeiten, ihre Standorte, ihr Einstellungsdatum oder andere Informationen speichern, die für Ihr Unternehmen relevant sind.

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, boolesch, Ganzzahl usw.), ob es einen einzelnen oder mehrere Werte haben kann und ob die Werte für alle 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 festlegen, wenn Sie Nutzer in Ihrer Domain aktualisieren, 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 die customSchemasEigenschaft und fügen Sie sie der Nutzerressource hinzu. In der Eigenschaft 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 einzelnen Wert werden als einfache Schlüssel/Wert-Paare festgelegt, z. B. "field1": "value1". Benutzerdefinierte Felder mit mehreren Werten werden als Arrays von Objekten festgelegt, wie die Standardfelder 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, 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 wird, 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
}

JSON-Anfrage

Der Aufruf im folgenden Beispiel aktualisiert einen Nutzer und legt Werte für das benutzerdefinierte Schema employmentData fest:

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 projection Parameter in einer users.get oder users.list Anfrage auf custom oder full setzen.

Benutzerdefinierte Felder in einem Nutzerprofil suchen

Sie können in benutzerdefinierten Feldern suchen, indem Sie den query Parameter in einer users.list Anfrage verwenden. Sie fordern das benutzerdefinierte Feld mit der Syntax schemaName.fieldName 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 über der Jobebene 7 liegen. Weitere Informationen finden Sie unter Nutzer suchen.

Benutzerdefiniertes Nutzerschema erstellen

Ein benutzerdefiniertes Nutzerschema kann allen Domains Ihres Google Workspace-Kontos hinzugefügt werden. Wenn Sie ein benutzerdefiniertes Nutzerschema in Ihren Domains erstellen möchten, verwenden Sie die folgende POST Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Informationen zu den Eigenschaften der Anfrage-Query-Strings finden Sie in der API-Referenz.

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

Bei allen Erstellungsanfragen müssen Sie die Informationen angeben, die zur Ausführung der Anfrage erforderlich sind. Wenn Sie Clientbibliotheken verwenden, werden die Datenobjekte aus der von Ihnen ausgewählten Sprache in JSON-formatierte Objekte konvertiert.

JSON-Anfrage

Das folgende Beispiel zeigt eine Anfrage zum Erstellen eines benutzerdefinierten Schemas. Die 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 wird der HTTP-Statuscode 201, zusammen mit den Attributen für das neue benutzerdefinierte Schema zurückgegeben.

Limits für benutzerdefinierte Schemas

  • Die maximale Anzahl benutzerdefinierter Schemas, die in einem Konto zulässig sind, beträgt 100.
  • Die maximale Anzahl benutzerdefinierter Felder, die in einem Konto zulässig sind, beträgt 100.
  • Die maximale Anzahl von Zeichen, die in einem string-Feld für ein benutzerdefiniertes Feld mit einem einzelnen Wert zulässig sind, 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.
  • Die in benutzerdefinierten Schemas und Feldnamen zulässigen Zeichen sind alphanumerische Zeichen, Unterstriche (_) und Bindestriche (-).
  • Das Ändern des Typs eines Felds ist nicht zulässig.
  • Ein Feld mit einem einzelnen Wert kann in ein Feld mit mehreren Werten umgewandelt werden, die umgekehrte Operation ist jedoch nicht zulässig.
  • Es ist nicht möglich, benutzerdefinierte Schemas oder Felder umzubenennen.

Benutzerdefiniertes Nutzerschema aktualisieren

Wenn Sie ein benutzerdefiniertes Schema aktualisieren möchten, verwenden Sie die folgende PUT Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Der 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

JSON-Anfrage

Im folgenden Beispiel enthielt das Schema employmentData bei der Erstellung ein Feld JobFamily. Die Anfrage aktualisiert employmentData so, dass es nur ein 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.

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

Benutzerdefiniertes Nutzerschema abrufen

Wenn Sie ein benutzerdefiniertes Schema abrufen möchten, verwenden Sie die folgende GET Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Der 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 wird der HTTP-Statuscode 200, 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

Wenn Sie alle benutzerdefinierten Schemas im selben Konto abrufen möchten, verwenden Sie die folgende GET Anfrage und fügen Sie die in 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

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200, 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"
        },
        {
          &quot;kind": "admin#directory#schema#fieldspec",
          "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
          "fieldType": "STRING",
          "fieldName": "JobFamily"
        }
      ]
    }
  ]
}