このページは Cloud Translation API によって翻訳されました。

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

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

まず、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/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" }
      ]
    }
  }
}

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

ユーザープロフィールのカスタムフィールドを取得するには、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"
        }
      ]
    }
  ]
}

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

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

JSON リクエスト

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

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

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

JSON リクエスト

カスタム スキーマの制限

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

JSON リクエスト

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

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

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

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

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

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

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

カスタムスキーマの制限

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

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

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