🌐
項目IDについて
この記事では、YESODディレクトリーサービスのAPI・インポート・クエリなどで項目（属性）を指定する際に使う項目ID（attributeId）について、取得方法・利用箇所・エイリアスが設定されている項目の一覧を説明します。
📋 関連記事 メンバー項目・グループ関連項目などの基本概念は YESOD ディレクトリーサービスのデータ構造について を前提としています。
項目IDとは項目IDの取得方法画面からコピーするAPIで一括取得する項目IDの利用箇所ディレクトリーサービスAPI：リクエストで指定する場合クエリAPI（検索条件・出力項目の指定）インポート・トランザクションインポートAPI（属性マッピング）ディレクトリーサービスAPI：レスポンスに含まれる場合クエリAPIグループAPIエラーメッセージでの項目特定アカウントコントロール属性式その他BigQuery連携エイリアスが設定されている項目一覧項目オプションのoptionIdについて関連記事
項目IDとは
項目ID（attributeId）は、YESODが扱う各項目（属性）を一意に識別するIDです。項目管理・オプション管理画面で定義した項目は、API・クエリからこの項目IDを通じて参照できます。
| 種別 | 位置付け | 項目IDの扱い |
|---|---|---|
| カスタム項目 | テナント独自に追加した項目 | 新しい項目IDが発行されます |
| 標準項目 | YESODがあらかじめ用意している項目（上書きの有無を問わず） | 上書きしても元の項目IDがそのまま使われます（新規発行されません） |
⚠️ 注意 項目名称（attributeLabel）は一意ではありません。たとえば「携帯電話」という名称の項目は、異なる項目IDで複数存在します。API連携やクエリの条件では、名称ではなく必ず項目IDで項目を特定してください。
💡 ポイント 項目IDにはBase64形式とUUID形式の2種類の表記があります。画面やAPIから取得できるのはBase64形式です。UUID形式は、同じ項目IDをハイフン区切りの36桁の16進数（標準的なUUIDの書式）で表したもので、Base64形式はこれを22文字に短縮した表記です。どちらも同じ項目IDを指しており、属性式など一部の設定ではUUID形式でも指定できます。詳細は 属性マッピングの設定 を参照してください。
項目IDの取得方法
画面からコピーする
対象によって、次の3通りの確認方法があります。
1. メンバー項目：従業員詳細画面から
従業員詳細画面で、対象項目のキャレット（ドロップダウンメニュー）から「項目のIDをコピー」を選択すると、その項目の項目IDがクリップボードにコピーされます。
2. クエリの検索条件・出力項目：保存済みのクイックビューから
保存済みのクイックビューのキャレットから「APIパラメータとして設定をコピー」を実行すると、そのクイックビューが内部的に使用しているクエリAPIのリクエストパラメータ（検索条件・出力項目の項目IDを含むJSON）がクリップボードにコピーされます。
💡 ポイント コピーした項目IDがどの項目かを特定するには、クイックビューで出力項目として指定した項目（表示順）と、コピーしたパラメータ内の項目IDの並び順を突き合わせる方法と、コピーしたパラメータでクエリAPIを実際に実行し、レスポンスに含まれると突き合わせる方法があります。
3. カスタム項目・標準項目の上書き：設定 > 項目管理から
設定 > 項目管理画面で、カスタム項目または標準項目の上書きの内容から項目IDを確認できます。対象の標準項目がまだ上書きされていない場合は、「新規上書き」から上書きを新規作成し、上書きする標準項目を選ぶプルダウンメニュー、または上書き後の編集画面で項目IDを確認できます。
APIで一括取得する
個々の画面からコピーする代わりに、属性一覧取得API（）を使うと、テナント内の全項目の項目ID・名称・データ型を一括取得できます。
json
💡 ポイント システム連携の初期設定時など、多数の項目IDをまとめて確認したい場合は、画面から1件ずつコピーするよりもこのAPIの利用がおすすめです。
💡 ポイント 実際のレスポンスには、項目管理・オプション管理画面には表示されない、システム内部で使用されている属性（ロールの権限フラグ、業務アセットの内部設定など）も多数含まれます。も、カスタム項目で選べる6種類（テキスト・数字・日付・セレクト・画像・ファイル）以外に・・・などが返ることがあります。連携で実際に扱う項目かどうかは、項目管理・オプション管理画面に表示されているものかどうかで判断してください。
項目IDの利用箇所
項目IDは、YESODディレクトリーサービスAPIのリクエスト・レスポンスの両方に加えて、アカウントコントロールの属性式、BigQuery連携やエラーメッセージなど、様々な箇所で使用されます。混同しやすいため、「APIのリクエストで指定する場合」と「APIのレスポンスに含まれる場合」を分けて説明します。
ディレクトリーサービスAPI：リクエストで指定する場合
クエリAPI（検索条件・出力項目の指定）
クエリAPI（）では、取得したい項目を指定する・、および検索条件のに項目IDを指定します。
json
（会社が登録されており、かつメールアドレスがのメンバーを検索し、姓・名・関与度合を取得する例）
インポート・トランザクションインポートAPI（属性マッピング）
インポートAPI・トランザクションインポートAPIの属性マッピング設定（）では、CSVの列と項目を対応付けるキーとして、項目ID（Base64形式・UUID形式のいずれも可）または後述の項目エイリアスを指定できます。同じの中で項目ID（Base64形式・UUID形式）と項目エイリアスを混在させて指定することも可能です。これはメンバーだけでなく、トランザクションインポートAPIの「トランザクション/グループインポート」（組織・会社・事業所・プロジェクトの登録・変更）でも同様です。
メンバーインポート（）の例
json
トランザクションインポート（）の例
json
トランザクション/グループインポート（組織のフルパス指定）の例
json
💡 ポイントで指定した区切り文字（この例では）で組織の階層を1つの列にまとめて指定でき、を指定するとフルパスで組織を名寄せします。
📋 関連記事 CSVマッピングの詳しい書き方は マッピングファイルの記載方法 を参照してください。
ディレクトリーサービスAPI：レスポンスに含まれる場合
クエリAPI
クエリAPIのレスポンスでも、各項目の値ごとにが付与されて返却されます（で指定した項目に限らず、検索条件にも同様に含まれます）。
json
グループAPI
グループAPI（）は、会社・組織・事業所・プロジェクトなどのグループ情報を、親子関係を持つツリー構造（で下位グループを再帰的に保持）で取得します。各グループの配列にある要素ので、どの項目の値かを識別します。
json
💡 ポイント クエリAPI・属性一覧取得APIのはのオブジェクトですが、グループAPIのは単一の文字列です。同じフィールド名でもAPIによって型が異なるため注意してください。
エラーメッセージでの項目特定
公開APIのエラーレスポンスでも項目IDが使われます。たとえば検索条件の値の型が項目と一致しない場合や、指定した項目が見つからない場合、メッセージ内に対象の項目ID（またはエイリアス）が含まれます。
| 状況 | メッセージ例 |
|---|---|
| 検索条件の値の型が項目と一致しない | |
| 指定した項目が見つからない |
💡 ポイント 連携先で項目IDの指定ミスが起きた場合、エラーメッセージに含まれる項目IDを手がかりに、どの項目の設定が誤っているかを特定できます。
アカウントコントロール
属性式
アカウントコントロールの業務アセットで「同期する項目」に設定する属性式でも、項目をエイリアス名・項目ID（Base64形式）・項目ID（UUID形式）のいずれでも指定できます。以下は、いずれもメールアドレスを指定した例です。3行とも同じ値を返します。
javascript
📋 関連記事 属性式の詳しい書き方・標準項目のエイリアス一覧は 属性式について を参照してください。
その他
BigQuery連携
BigQuery連携の「項目一覧」出力では列（Base64形式）に項目IDが、「項目オプション一覧」出力では紐づく項目のが出力されます。それぞれ専用のコンテナイメージをCloud Runにデプロイして実行します。
| 用途 | コンテナイメージのURL |
|---|---|
| 項目一覧をBigQueryにインポート | |
| 項目オプション一覧をBigQueryにインポート |
メンバー情報・会社情報・組織情報・事業所情報・プロジェクト情報の出力（コンテナイメージを共通で使用し、環境変数で対象を切り替えます）でも、2つの環境変数で項目IDを扱います。
- 環境変数（任意）：カンマ区切りで項目ID（attributeId）を指定すると、出力する項目を絞り込めます。未指定の場合はすべての項目が出力されます。
- 環境変数（任意）：を設定すると、各フィールド名が「項目名」から「項目名_AttributeId」に変わり、フィールド名に項目ID（AttributeId）が含まれるようになります。
| 対象情報 | 環境変数を指定しない場合 | の場合 |
|---|---|---|
| メンバー情報・会社情報・組織情報・事業所情報・プロジェクト情報 | フィールド名は項目名のみ | フィールド名が「項目名_AttributeId」になる |
💡 ポイント 同一テーブル内に同名の項目（attributeLabelが重複するケース）があると、BigQuery側で「Field [項目名] already exists in schema」というエラーになります。をに設定してフィールド名に項目IDを含めるか、項目管理画面で項目名称を一意にすることで回避できます。
📋 関連記事 環境変数の詳細は BigQuery連携(β) を参照してください。
項目オプションのoptionIdについて
📋 関連記事 セレクト項目の選択肢（オプション）にも、項目IDとは別に一意のoptionIdが割り当てられています。項目オプションマスタ画面や項目オプションAPIから取得できます。詳細は 項目オプションAPI を参照してください。