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 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 es einen oder mehrere Werte hat 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 beim Aktualisieren von Nutzern in Ihrer Domain festlegen, 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 eine customSchemasEigenschaft und fügen Sie sie der Nutzerressource hinzu. Innerhalb des Attributs 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 standardmäßigen Felder 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 festgelegt 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 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 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/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 durchsuchen

Mit dem Parameter query in einer users.list-Anfrage können Sie in benutzerdefinierten Feldern suchen. Sie fordern das benutzerdefinierte Feld mit der 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 über der 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. 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 Attributen des Anfrage-Query-Strings 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 Bearbeitung 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. 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 wird der HTTP-Statuscode 201 zusammen mit den Attributen für das neue benutzerdefinierte Schema zurückgegeben.

Einschränkungen bei benutzerdefinierten Schemas

  • In einem Konto sind maximal 100 benutzerdefinierte Schemas zulässig.
  • In einem Konto sind maximal 100 benutzerdefinierte Felder zulässig.
  • Die maximale Anzahl zulässiger Zeichen in einem string-Feld für ein benutzerdefiniertes Feld mit einem einzelnen Wert beträgt 500. Bei benutzerdefinierten Feldern mit mehreren Werten hängt die zulässige Anzahl von Elementen 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 alphanumerische Zeichen, Unterstriche (_) und Bindestriche (-) zulässig.
  • Der Typ eines Felds darf nicht geändert werden.
  • Ein Feld mit einem einzelnen Wert kann in ein Feld mit mehreren Werten umgewandelt werden, die umgekehrte Operation ist jedoch nicht zulässig.
  • Benutzerdefinierte Schemas oder Felder können nicht umbenannt werden.

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. 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

JSON-Anfrage

Im folgenden Beispiel enthielt das Schema employmentData bei der ursprünglichen Erstellung das Feld JobFamily. In der Anfrage wird employmentData so aktualisiert, dass es 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 einreichen, die zur Bearbeitung 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. 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 wird der HTTP-Statuscode 200 zusammen mit den Eigenschaften 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"
        },
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
          "fieldType": "STRING",
          "fieldName": "JobFamily"
        }
      ]
    }
  ]
}