コンテナーメタデータの格納とクエリ

適用対象: 開発者

アプリで 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 プロパティサフィックスを使用) については、「コンテナーとファイルの検索」を参照してください。 1 つのコンテナードライブ内の構造化クエリに OData $filter を使用します。多くのコンテナーで自由テキストクエリを検索します。

スキーマの整合性を維持する

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

次の手順

ファイルを共有し、アクセス許可を管理する

Last updated on 2026-07-15