Catalog - Search

Service:
Core
API バージョン:
v1

カタログ検索 API を使用すると、ワークスペース間で OneLake カタログ エントリをプログラムで検出できます。 カタログ メタデータに対するクロスワークスペース検索をサポートし、呼び出し元プリンシパルがアクセスを許可されているエントリにフィルター処理された結果を返します。 検索結果には、補足的な Fabric API と共に使用して追加の詳細を取得したり、サポートされているアクションを実行したりするための安定した識別子が含まれます。

注

カタログ検索は現在プレビュー段階です (詳細については、こちらをご覧ください)。

CatalogEntry は、Microsoft Fabric エンティティの検出可能なメタデータ表現であり、現在はワークスペースアイテムにスコープが設定されています。 カタログ エントリはメタデータの検出のみを目的としており、基になるデータやアイテムのコンテンツへのアクセス権は付与されません。

Permissions

呼び出し元は、呼び出し元がアクセスを許可されているワークスペースとアイテムのカタログ エントリのみを検出できます。

必要な委任スコープ

Catalog.Read.All

制限事項

  • continuationToken は、 search または filterと組み合わせてはなりません。 トークンには、元の要求からこれらの値が既に含まれています。

  • pageSize は 1 から 1000 の間である必要があります。

Microsoft Entra でサポートされている ID

この API では、このセクションに記載されている Microsoft ID がサポートされています。

アイデンティティ サポート
User はい
サービス プリンシパルとマネージド ID はい

インターフェイス

POST https://api.fabric.microsoft.com/v1/catalog/search

要求本文

Name 型 説明
continuationToken

string

次のページの継続トークン。

継続トークンは、元の要求の search、 filter、および pageSize を転送するため、それ自体で送信できます。 同じ要求内の search または filter と組み合わせて使用することはできません。これを行うとエラーが返されます。
filter

string

検索のフィルター。 時間の経過と伴って追加のフィルター オプションが追加される場合があります。

フィルター パラメーターは、次のプロパティをサポートしています。

  • 型: カタログ エントリの type プロパティ ( Report、 Lakehouse、 Workspaceなど) と一致します。 1 つのフィルターで最大 500 個の Type 値を指定でき、それぞれ最大 50 文字を指定できます。

  • WorkspaceId: カタログ エントリを含むワークスペースの ID。 1 つのフィルターで最大 12 個の WorkspaceId 値を指定できます。各値は有効な GUID である必要があります。

フィルター パラメーターは、結果を絞り込むための次の演算子をサポートしています。

  • eq: 等しい。は正確な値と一致します。

  • ne: 等しくない。は、指定された値を除外します。

  • and: Logical AND;は、すべての条件が true の場合にのみ一致します。

  • または: 論理 OR;は、いずれかの条件が true の場合に一致します。

  • ( ): かっこ;は、論理階層を定義する式をグループにします。
pageSize

integer

返される必要があるページ サイズ。 ページ サイズは 1 から 1000 の間である必要があります。 既定値は 50 です。
search

string

検索のテキスト クエリ。 このフィールドは、CatalogEntry の表示名、ワークスペースの表示名、および説明の検索をサポートします。

検索フィールドは、次の演算子をサポートしています。

  • " " : 二重引用符;は、囲まれた単語を正確な語句として一致させます。

  • * : アスタリスク;0 個以上の文字に一致するワイルドカード。

  • ? : 疑問符;1 文字に一致するワイルドカード。

  • & : 二重アンパサンド;すべての検索語句が必要です。

  • アンダースコアは検索語句の一部として扱われます。エスケープは必要ありません。

  • その他の特殊文字は無視され、区切り記号として扱われます。

応答

Name 型 説明
200 OK

CatalogQueryResponse

[OK]
429 Too Many Requests

ErrorResponse

サービス レートの制限を超えました。 サーバーは、クライアントが追加の要求を送信するまでに待機する必要がある時間を秒単位で示す Retry-After ヘッダーを返します。

ヘッダー

Retry-After: integer
Other Status Codes

ErrorResponse

一般的なエラー コード:

  • InvalidRequest - 要求本文が指定されていないか、それ以外の場合は無効です。

  • InvalidSearch - search 値を解析できませんでした。

  • InvalidFilter - filter を解析できなかったか、フィルター値の形式が正しくないか、その最大長を超えています。

  • InvalidFilterProperty - filter は、サポートされていないプロパティを参照します。

  • FilterTooManyValues - filter は、そのプロパティで許可される値よりも多くの値をプロパティに指定します。

  • FilterNotSupported - フィルター処理はサポートされていません。

  • ConflictingFilterParameters - continuationToken が search または filterと組み合わされました。

  • InvalidPageSize - pageSize が 1 から 1000 の範囲外です。

  • InvalidContinuationToken - continuationToken が無効です。

  • ContinuationTokenTooLong - continuationToken が最大長を超えています。

  • TypeNotFound - filter は、存在しない項目の種類を参照します。

  • 未承認 - 認証が見つからないか無効です

  • 内部サーバー エラー - 予期しないサービスエラー。

例

Search example
Search within a workspace example

Search example

要求のサンプル

POST https://api.fabric.microsoft.com/v1/catalog/search

{
  "search": "sales",
  "pageSize": 3,
  "filter": "Type eq 'Report' or Type eq 'Lakehouse' or Type eq 'Workspace'"
}

応答のサンプル

状態コード:
200 
{
  "value": [
    {
      "id": "0acd697c-1550-43cd-b998-91bfb12347c6",
      "type": "Report",
      "catalogEntryType": "FabricItem",
      "displayName": "Monthly Sales Revenue",
      "description": "Consolidated revenue report for the current fiscal year.",
      "hierarchy": {
        "workspace": {
          "id": "7f2c8a91-3b4d-4e5f-a6b7-c8d9e0f1a2b3",
          "displayName": "Sales Analytics"
        }
      }
    },
    {
      "id": "5e8f2a1b-9c3d-4e7f-b6a5-d4c3b2a1e0f9",
      "type": "Lakehouse",
      "catalogEntryType": "FabricItem",
      "displayName": "Sales Revenue Lakehouse",
      "description": "Central lakehouse for sales transaction data.",
      "hierarchy": {
        "workspace": {
          "id": "a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d",
          "displayName": "Finance Platform"
        }
      }
    },
    {
      "id": "7f2c8a91-3b4d-4e5f-a6b7-c8d9e0f1a2b3",
      "type": "Workspace",
      "catalogEntryType": "Workspace",
      "displayName": "Sales Analytics",
      "description": "Workspace for the sales analytics team."
    }
  ],
  "continuationToken": "eyJza2lwIjozLCJ0YWtl..."
}

Search within a workspace example

要求のサンプル

POST https://api.fabric.microsoft.com/v1/catalog/search

{
  "search": "revenue",
  "filter": "(Type eq 'Report' or Type eq 'SemanticModel') and WorkspaceId eq '7f2c8a91-3b4d-4e5f-a6b7-c8d9e0f1a2b3'",
  "pageSize": 2
}

応答のサンプル

状態コード:
200 
{
  "value": [
    {
      "id": "0acd697c-1550-43cd-b998-91bfb12347c6",
      "type": "Report",
      "catalogEntryType": "FabricItem",
      "displayName": "Monthly Sales Revenue",
      "description": "Consolidated revenue report for the current fiscal year.",
      "hierarchy": {
        "workspace": {
          "id": "7f2c8a91-3b4d-4e5f-a6b7-c8d9e0f1a2b3",
          "displayName": "Sales Analytics"
        }
      }
    },
    {
      "id": "c41d9f2e-7b60-4a15-8d3c-2f6e9a0b7c48",
      "type": "SemanticModel",
      "catalogEntryType": "FabricItem",
      "displayName": "Revenue Semantic Model",
      "description": "Shared revenue model backing the sales reports.",
      "hierarchy": {
        "workspace": {
          "id": "7f2c8a91-3b4d-4e5f-a6b7-c8d9e0f1a2b3",
          "displayName": "Sales Analytics"
        }
      }
    }
  ],
  "continuationToken": "eyJza2lwIjoyLCJ0YWtl..."
}

定義

Name 説明
CatalogEntryType

カタログ エントリの種類。 追加の CatalogEntryType 型は、時間の経過と同時に追加される場合があります。
CatalogQueryRequest

検索のクエリ。
CatalogQueryResponse

検索結果。
CatalogWorkspace

カタログ エントリのワークスペース。
ErrorParameter

エラーに関する追加のコンピューター読み取り可能なコンテキストを提供する構造化パラメーター。
ErrorRelatedResource

エラー関連のリソース詳細オブジェクト。
ErrorResponse

エラー応答。
ErrorResponseDetails

エラー応答の詳細。
ItemCatalogEntry

Fabricアイテムのカタログ メタデータ表現。
ItemCatalogEntryHierarchy

Fabricのデータ アーキテクチャ内のアイテムの直属の先祖。 該当するレベルのみが返されます。
ItemType

アイテムの種類。 追加の項目の種類は、時間の経過と同時に追加される場合があります。
WorkspaceCatalogEntry

Fabric ワークスペースのカタログ メタデータ表現。
WorkspaceCatalogEntryType

ワークスペース カタログ エントリで報告される型。 追加の WorkspaceCatalogEntryType 型は、時間の経過と同時に追加される場合があります。

CatalogEntryType

列挙

カタログ エントリの種類。 追加の CatalogEntryType 型は、時間の経過と同時に追加される場合があります。

値 説明
FabricItem

ファブリック アイテム カタログエントリの種類。
Workspace

ワークスペース カタログエントリの種類。

CatalogQueryRequest

Object

検索のクエリ。

Name 型 説明
continuationToken

string

次のページの継続トークン。

継続トークンは、元の要求の search、 filter、および pageSize を転送するため、それ自体で送信できます。 同じ要求内の search または filter と組み合わせて使用することはできません。これを行うとエラーが返されます。
filter

string

検索のフィルター。 時間の経過と伴って追加のフィルター オプションが追加される場合があります。

フィルター パラメーターは、次のプロパティをサポートしています。

  • 型: カタログ エントリの type プロパティ ( Report、 Lakehouse、 Workspaceなど) と一致します。 1 つのフィルターで最大 500 個の Type 値を指定でき、それぞれ最大 50 文字を指定できます。

  • WorkspaceId: カタログ エントリを含むワークスペースの ID。 1 つのフィルターで最大 12 個の WorkspaceId 値を指定できます。各値は有効な GUID である必要があります。

フィルター パラメーターは、結果を絞り込むための次の演算子をサポートしています。

  • eq: 等しい。は正確な値と一致します。

  • ne: 等しくない。は、指定された値を除外します。

  • and: Logical AND;は、すべての条件が true の場合にのみ一致します。

  • または: 論理 OR;は、いずれかの条件が true の場合に一致します。

  • ( ): かっこ;は、論理階層を定義する式をグループにします。
pageSize

integer

返される必要があるページ サイズ。 ページ サイズは 1 から 1000 の間である必要があります。 既定値は 50 です。
search

string

検索のテキスト クエリ。 このフィールドは、CatalogEntry の表示名、ワークスペースの表示名、および説明の検索をサポートします。

検索フィールドは、次の演算子をサポートしています。

  • " " : 二重引用符;は、囲まれた単語を正確な語句として一致させます。

  • * : アスタリスク;0 個以上の文字に一致するワイルドカード。

  • ? : 疑問符;1 文字に一致するワイルドカード。

  • & : 二重アンパサンド;すべての検索語句が必要です。

  • アンダースコアは検索語句の一部として扱われます。エスケープは必要ありません。

  • その他の特殊文字は無視され、区切り記号として扱われます。

CatalogQueryResponse

Object

検索結果。

Name 型 説明
continuationToken

string

次のページの continuationToken。
value CatalogEntry[]:

カタログ エントリの一覧

CatalogWorkspace

Object

カタログ エントリのワークスペース。

Name 型 説明
displayName

string

ワークスペースの表示名。
id

string (uuid)

ワークスペースの ID。

ErrorParameter

Object

エラーに関する追加のコンピューター読み取り可能なコンテキストを提供する構造化パラメーター。

Name 型 説明
message

string

パラメーターの意味を人間が判読できる説明。
name

string

パラメータ識別子です。
value

string

パラメーターの値を指定します。

ErrorRelatedResource

Object

エラー関連のリソース詳細オブジェクト。

Name 型 説明
resourceId

string

エラーに関係するリソース ID。
resourceType

string

エラーに関係するリソースの種類。

ErrorResponse

Object

エラー応答。

Name 型 説明
errorCode

string

エラー状態に関する情報を提供し、サービスとそのユーザー間の標準化された通信を可能にする特定の識別子。
isRetriable

boolean

true の場合、要求を再試行できます。 Retry-After応答ヘッダーを使用して、遅延 (使用可能な場合) を決定します。
message

string

エラーの人間が理解可能な表現。
moreDetails

ErrorResponseDetails[]

その他のエラーの詳細の一覧。
parameters

ErrorParameter[]

エラーに関する追加のコンピューター読み取り可能なコンテキストを提供する構造化パラメーター。
relatedResource

ErrorRelatedResource

エラー関連のリソースの詳細。
requestId

string (uuid)

エラーに関連付けられている要求の ID。

ErrorResponseDetails

Object

エラー応答の詳細。

Name 型 説明
errorCode

string

エラー状態に関する情報を提供し、サービスとそのユーザー間の標準化された通信を可能にする特定の識別子。
message

string

エラーの人間が理解可能な表現。
parameters

ErrorParameter[]

エラーに関する追加のコンピューター読み取り可能なコンテキストを提供する構造化パラメーター。
relatedResource

ErrorRelatedResource

エラー関連のリソースの詳細。

ItemCatalogEntry

Object

Fabricアイテムのカタログ メタデータ表現。

Name 型 説明
catalogEntryType string:

FabricItem

カタログ エントリの種類。
description

string

カタログ エントリの説明。
displayName

string

カタログ エントリの表示名。
hierarchy

ItemCatalogEntryHierarchy

カタログ エントリの階層。
id

string (uuid)

カタログ エントリの objectId。
type

ItemType

ファブリック項目の種類。

ItemCatalogEntryHierarchy

Object

Fabricのデータ アーキテクチャ内のアイテムの直属の先祖。 該当するレベルのみが返されます。

Name 型 説明
workspace

CatalogWorkspace

アイテムを含むワークスペース。

ItemType

列挙

アイテムの種類。 追加の項目の種類は、時間の経過と同時に追加される場合があります。

値 説明
Dashboard

PowerBI ダッシュボード。
Report

PowerBI レポート。
SemanticModel

PowerBI セマンティック モデル。
PaginatedReport

PowerBI のページ分割されたレポート。
Datamart

PowerBI データマート。
Lakehouse

レイクハウス。
Eventhouse

イベントハウス。
Environment

環境。
KQLDatabase

KQL データベース。
KQLQueryset

KQL クエリセット。
KQLDashboard

KQL ダッシュボード。
DataPipeline

データ パイプライン。
Notebook

ノートブック。
SparkJobDefinition

Spark ジョブ定義。
MLExperiment

機械学習の実験。
MLModel

機械学習モデル。
Warehouse

倉庫。
Eventstream

イベントストリーム。
SQLEndpoint

SQL エンドポイント。
MirroredWarehouse

ミラー化された倉庫。
MirroredDatabase

ミラー化されたデータベース。
Reflex

反射。
GraphQLApi

GraphQL 項目の API。
MountedDataFactory

MountedDataFactory。
SQLDatabase

SQLDatabase。
CopyJob

コピー ジョブ。
VariableLibrary

VariableLibrary。
Dataflow

データフロー。
ApacheAirflowJob

ApacheAirflowJob。
WarehouseSnapshot

Warehouse スナップショット。
DigitalTwinBuilder

DigitalTwinBuilder。
DigitalTwinBuilderFlow

デジタル ツイン ビルダー フロー。
MirroredAzureDatabricksCatalog

ミラー化された Azure databricks カタログ。
Map

マップ。
AnomalyDetector

Anomaly Detector。
UserDataFunction

ユーザー データ関数。
GraphModel

GraphModel。
GraphQuerySet

Graph QuerySet。
SnowflakeDatabase

Snowflake アカウントから作成された Iceberg テーブルを格納する Snowflake データベース。
OperationsAgent

OperationsAgent。
CosmosDBDatabase

Cosmos DB データベース。
Ontology

オントロジ。
EventSchemaSet

EventSchemaSet。
DataAgent

DataAgent。
MirroredCatalog

MirroredCatalog。
PolicySet

PolicySet。
AppBackend

AppBackend。
OrgApp

組織アプリ。
OrgAppAudience

組織アプリの対象ユーザー。
DataBuildToolJob

DataBuildToolJob。
AzureDatabricksStorage

Azure Databricksの OneLake に基づくストレージ項目。
Plan

プラン。

WorkspaceCatalogEntry

Object

Fabric ワークスペースのカタログ メタデータ表現。

Name 型 説明
catalogEntryType string:

Workspace

カタログ エントリの種類。
description

string

カタログ エントリの説明。
displayName

string

カタログ エントリの表示名。
id

string (uuid)

カタログ エントリの objectId。
type

WorkspaceCatalogEntryType

カタログ エントリの種類。 ワークスペース カタログ エントリの場合は常に Workspace 。

WorkspaceCatalogEntryType

列挙

ワークスペース カタログ エントリで報告される型。 追加の WorkspaceCatalogEntryType 型は、時間の経過と同時に追加される場合があります。

値 説明
Workspace

ワークスペース。