コンテナーメタデータの保存と照会

適用対象: Developer

アプリで SharePoint Embedded コンテナー内のファイルに構造化フィールドが必要な場合は、メタデータを使用します。メタデータは、 fileStorageContainer の列として、およびコンテナードライブの項目のフィールド値として格納されます。アプリケーションは、各コンテナーインスタンスの列スキーマの作成と管理を担当します。コンテナーリソースプロパティの完全な一覧については、「 fileStorageContainer リソースの種類」を参照してください。

アクセス許可とサポートされる呼び出し元

アプリ専用または委任されたベアラートークンを使用してメタデータ API を呼び出します。アプリケーション呼び出しと委任呼び出しには FileStorageContainer.Selected を使用します。

コンテナーの所有者と管理者は、列を作成、更新、削除できます。コンテナーメンバーは、列の読み取りと一覧表示を行うことができます。

列の種類の選択

SharePoint Embedded メタデータがサポートしている列の型プロパティは、 boolean、 choice、 currency、 dateTime、 hyperlinkOrPicture、 number、 personOrGroup、 text です。また、 indexed、 isDeletable、 isSealed、 name、 readOnly、 type などの列の設定もサポートされています。

列名は SharePoint ルールに従う必要があります。 !を含む名前、数字または句読点で始まる名前、スペースを含む名前、スプレッドシートのセル参照のように見える名前、ローカライズされた true/false 値を表す名前、Author、Created、Description などの予約名の使用はしないでください。

列の作成

ファイルにフィールド値を書き込む前に、コンテナーに列を作成します。

POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns
Content-Type: application/json

{
  "description": "test",
  "displayName": "Title",
  "enforceUniqueValues": false,
  "hidden": false,
  "indexed": false,
  "name": "Title",
  "text": {
    "allowMultipleLines": false,
    "appendChangesToExistingText": false,
    "linesForEditing": 0,
    "maxLength": 255
  }
}

作成要求は type をサポートしていないため、テキスト maxLength は 255 以下にする必要があります。

注:

2026 年 1 月の時点で、コンテナー列 API (列の一覧表示、作成、更新、削除) も v1.0 Microsoft Graph エンドポイントで一般提供されています。下の列 [要求] で /beta/ を /v1.0/ に置き換えることができます。ベータエンドポイントは引き続き使用できます。

列の管理

作成操作または一覧表示操作によって返される列 ID を使用します。

GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns
GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}
PATCH https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}
DELETE https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}

スキーマが変更されたときにサポートされているプロパティにパッチを適用します。 id プロパティ以外の列の任意のプロパティを更新できます。

{
  "required": true,
  "hidden": false,
  "description": "This is my new column description"
}

ファイルメタデータの読み取りと書き込み

フィールド値は、ドライブ項目のリスト項目フィールドに格納されます。すべてのフィールドを読み取るか、UI で必要なフィールドを選択します。

GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields
GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields?$select=Name,Color

メタデータを更新するためのパッチフィールド値。列で空の値が許可されている場合は、 null を使用してフィールド値をクリアします。

PATCH https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields
Content-Type: application/json

{
  "Color": "Fuchsia",
  "Quantity": 934
}

{
  "Color": null
}

メタデータによるファイルのクエリ

コンテナードライブ内で構造化されたフィルター処理または順序付けが必要な場合は、カスタム列で OData クエリオプションを使用します。

GET https://graph.microsoft.com/beta/drives/{drive-id}/items?$orderby=listitem/fields/TestField asc&$filter=startswith(listitem/fields/TestField, '3')&$expand=listitem($expand=fields)

結果に応答にフィールド値が必要な場合は、 $expand=listitem($expand=fields) を使用します。アプリが頻繁に実行する高カーディナリティフィルター用にインデックス付き列を作成します。

コンテナーとカスタムメタデータ間のフルテキスト検索については、「コンテナーとファイルの検索」を参照してください。インデックス付きカスタムメタデータでセマンティック取得をフィルター処理するには、「カスタムメタデータで取得をフィルター処理する」を参照してください。どちらのエクスペリエンスでも、テキスト列用に生成された OWSTEXT プロパティなどの SharePoint 管理プロパティが使用されます。

1 つのコンテナードライブ内の構造化されたクエリには OData $filter を使用します。多数のコンテナーにわたってフリーテキストクエリを検索するか、検索 API を使用して AI グラウンディングの抽出を返します。

スキーマの一貫性を維持する

コンテナーのプロビジョニング中に必要な列を作成します。予想されるスキーマバージョンをアプリデータに格納し、新しい列が導入されたときに移行を実行します。ワークフロー、クエリ、エクスポート、または検索エクスペリエンスがその値に依存しないことがわからない限り、列を削除しないでください。

次の手順

ファイルの共有とアクセス許可の管理

Last updated on 2026-09-18