カスタム ユーザー フィールドの管理

カスタム ユーザー スキーマをドメインに追加することで、ドメインのユーザー向けにカスタム フィールドを定義できます。これらのフィールドを使用して、ユーザーが従事しているプロジェクト、物理的な場所、雇用日などの、ビジネスニーズに合ったどんな情報でも保存できます。

まず、1 つ以上のスキーマを作成して、ドメインに合ったカスタム フィールドを定義します。フィールドの名前、型（文字列、ブール値、整数など）、単一値か複数値か、その属性の値をドメイン内のすべてのユーザーが閲覧できるか管理者と関連するユーザーのみが閲覧できるかなどの多数の属性を指定できます。

スキーマが定義されると、カスタム フィールドは標準フィールドと同じように動作します。ドメインのユーザーを更新するときに設定したり、users.get と users.list で取得したり、カスタム フィールドを検索したりできます。

ユーザー プロフィールにカスタム フィールドを設定する

スキーマを更新または作成するには、customSchemas プロパティを作成して、ユーザーのリソースに追加します。customSchemas プロパティ内では、カスタム フィールドは標準の JSON 形式でスキーマ別にグループ化されます。

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

単一値のカスタム フィールドは、"field1": "value1" のような単純な Key-Value ペアとして設定されます。複数値を持つカスタム フィールドは、addresses や phones などの API の標準複数値フィールドのような、オブジェクトの配列として設定されます。これらの値オブジェクトは、次のキーをサポートしています。

キー
value 保存する値（必須）。
type 値のタイプ（省略可）。有効な値は次のとおりです。
  • custom
  • home
  • other
  • work
customType 値のカスタムタイプ（省略可）。type が custom に設定されている場合には必ず使用します。

更新時にスキーマ内のカスタム フィールドが指定されていない場合、変更されません。更新時に customFields にスキーマ自体が指定されていない場合、そのスキーマ内のすべてのカスタム フィールドは変更されません。プロフィールからカスタム フィールドまたはカスタム スキーマを削除するには、明示的に null に設定する必要があります。

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

JSON リクエスト

以下の呼び出し例では、ユーザーを更新して employmentData カスタム スキーマの値を設定しています。

PATCH https://admin.googleapis.com/admin/directory/v1/users/[email protected]

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

ユーザー プロフィールのカスタム フィールドを読み取る

ユーザー プロフィールのカスタム フィールドを取得するには、users.get リクエストまたは users.list リクエストの projection パラメータを custom または full に設定します。

ユーザー プロフィールのカスタム フィールドを検索する

users.list リクエストで query パラメータを使用すると、カスタム フィールド内を検索できます。カスタム フィールドは schemaName.fieldName 構文でリクエストします。次に例を示します。

employmentData.projects:"GeneGnome"

は、プロジェクト GeneGnome で働く全従業員を返します。クエリ

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

は、職位が 7 を超える、アトランタのすべての従業員を返します。詳細については、ユーザーを検索するをご覧ください。

カスタム ユーザー スキーマを作成する

カスタム ユーザー スキーマは、Google Workspace アカウントのすべてのドメインに追加できます。ドメインでカスタム ユーザー スキーマを作成するには、次の POST リクエストを使用し、その際にはリクエストを承認するで説明されている承認を含めます。リクエストのクエリ文字列のプロパティについては、API リファレンスをご覧ください。

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

すべての作成リクエストでは、リクエストの実行に必要な情報を送信する必要があります。クライアント ライブラリを使用している場合は、選択した言語のデータ オブジェクトを JSON データ形式のオブジェクトに変換します。

JSON リクエスト

次のサンプルは、カスタム スキーマを作成するリクエストを示しています。リクエストとレスポンスのプロパティの完全なリストについては、API リファレンスをご覧ください。

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

成功すると、レスポンスとして HTTP 201 のステータス コードと新しいカスタム スキーマのプロパティが返されます。

カスタム スキーマの制限

  • 1 つのアカウントに許されるカスタム スキーマの最大数は 100 です。
  • 1 つのアカウントに許されるカスタム フィールドの最大数は 100 です。
  • 単一値のカスタム フィールドの string フィールドの最大文字数は 500 です。複数値のカスタム フィールドの場合、許される要素の数は、割り当てられた値のサイズによって異なります。たとえば、それぞれ 100 文字の値 150 個、またはそれぞれ 500 文字の値 50 個を追加できます。
  • カスタム スキーマとカスタム フィールドの名前に使用できるのは、英数字、アンダースコア（_）、ハイフン（-）です。
  • フィールドのタイプは変更できません。
  • 単一値のフィールドを複数値にすることはできますが、その逆はできません。
  • カスタム スキーマまたはフィールドの名前を変更することはできません。

カスタム ユーザー スキーマを更新する

カスタム スキーマを更新するには、次の PUT リクエストを使用し、その際にはリクエストを承認するで説明されている承認を含めます。schemaKey は、スキーマ名または一意のスキーマ id です。リクエストとレスポンスのプロパティについては、API リファレンスをご覧ください。

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

JSON リクエスト

次の例のスキーマ employmentData には、当初 JobFamily フィールドが含まれていました。リクエストで employmentData が更新され、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"
    }
  ]
}

すべての更新リクエストでは、リクエストの実行に必要な情報を送信する必要があります。

成功すると、レスポンスとして更新されたスキーマ リソースと HTTP 200 ステータス コードが返されます。

カスタム ユーザー スキーマを取得する

カスタム スキーマを取得するには、次の GET リクエストを使用し、その際にはリクエストを承認するで説明されている承認を含めます。schemaKey は、スキーマ名または一意のスキーマ id です。リクエストとレスポンスのプロパティについては、API リファレンスをご覧ください。

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

成功すると、レスポンスとして HTTP 200 のステータス コードとカスタム スキーマのプロパティが返されます。

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

すべてのカスタム ユーザー スキーマを取得する

同じアカウントのカスタム スキーマをすべて取得するには、次の GET リクエストを使用し、その際にはリクエストを承認するで説明されている承認を含めます。リクエストとレスポンスのプロパティについては、API リファレンスをご覧ください。

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

成功すると、レスポンスとしてアカウントのカスタム スキーマと HTTP 200 ステータス コードが返されます。

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