Catalog - Search

服務:
Core
API 版本:
v1

目錄搜尋 API 允許跨工作區程式化發現 OneLake 目錄條目。 它支援跨工作空間搜尋目錄中繼資料，並回傳經過篩選至呼叫主體授權存取的條目的結果。 搜尋結果包含穩定識別碼，旨在與互補的 Fabric API 使用，以擷取額外細節或執行支援的動作。

備註

目錄搜尋目前處於預覽階段（了解更多）。

目錄條目是一種可發現的 Microsoft Fabric 實體的元資料表示法，目前僅限於工作區項目。 目錄條目僅用於元資料發現，並不授權存取底層資料或項目內容。

許可

來電者只能發現其授權存取的工作區和項目的目錄條目。

必要的委派範圍

目錄。全部閱讀

局限性

  • continuationToken 不得與 search 或 filter結合。 憑證本身就帶有原始請求的這些值。

  • pageSize 必須介於1到1000之間。

節流限制

限制類型 價值
平台 API 統一配額 每分鐘500通電話
API 限制 每分鐘50通電話

Microsoft Entra 支援的身份識別

此 API 支援本節中列出的Microsoft 身分識別。

身分識別 支援
User 是的
服務主體 與 受管理身份 是的

介面

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

要求本文

名稱 類型 Description
continuationToken

string

下一頁的續寫標記。

延續權杖會將原始請求的 、 filter、 pageSize 和 傳遞search，因此可以單獨傳送。 該請求不得與或合併searchfilter於同一請求中;否則會回傳錯誤。
filter

string

搜尋篩選器。 隨著時間推移，可能會新增更多篩選選項。

濾波參數支援以下特性：

  • 類型：與目錄條目的屬性相匹配 type ，例如 Report、 Lakehouse、 Workspace或 。 單一濾波器最多可指定 500 個類型值，每個值最多 50 個字元。

  • WorkspaceId：包含目錄條目的工作空間的 ID。 單一濾鏡最多只能指定 12 個 WorkspaceId 值，每個值必須是有效的 GUID。

濾波參數支援以下運算子以精煉結果：

  • eq：相等;完全符合該數值。

  • ne：不平等;排除指定的值。

  • 以及：邏輯與;只有當所有條件都成立時才匹配。

  • 或：邏輯或;如果符合任何條件，則為匹配。

  • （ ）： 括號;群組表達式以定義邏輯階層。
pageSize

integer

需要退還的頁面大小。 頁面大小必須介於1到1000之間。 預設為 50。
search

string

搜尋的文字查詢。 此欄位支援在 CatalogEntry 的顯示名稱、工作區顯示名稱及描述中搜尋。

搜尋欄位支援以下運算子：

  • “ ” ： 雙引號;將附上的詞彙精確匹配。

  • * ：星號;萬用卡匹配零個或多個字元。

  • ? ：問號;萬用卡匹配單一角色。

  • & & ： 雙&符號;必須要求所有搜尋詞。

  • 底線被視為搜尋詞的一部分;不需要逃跑。

  • 其他特殊字元則被忽略，並視為分隔符。

回覆

名稱 類型 Description
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 與或 filter合併search。

  • 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..."
}

定義

名稱 Description
CatalogEntryType

目錄條目類型。 可能會隨著時間新增其他 CatalogEntryType 類型。
CatalogQueryRequest

搜尋的查詢。
CatalogQueryResponse

搜尋結果。
CatalogWorkspace

目錄條目的工作區。
ErrorParameter

一個結構化參數，提供關於錯誤的額外機器可讀上下文。
ErrorRelatedResource

錯誤相關的資源詳細資料物件。
ErrorResponse

錯誤回應。
ErrorResponseDetails

錯誤回應的細節。
ItemCatalogEntry

Fabric 項目的目錄中繼資料表示。
ItemCatalogEntryHierarchy

是 Fabric 資料架構中該項目的直接祖先。 僅回傳適用的等級。
ItemType

項目的類型。 可能會隨著時間新增其他項目類型。
WorkspaceCatalogEntry

Fabric 工作區的目錄元資料表示。
WorkspaceCatalogEntryType

該類型在工作區目錄中回報。 可能會隨著時間新增其他 WorkspaceCatalogEntryType 類型。

CatalogEntryType

列舉型別

目錄條目類型。 可能會隨著時間新增其他 CatalogEntryType 類型。

值 Description
FabricItem

一種 Fabric 商品目錄的輸入類型。
Workspace

一種工作空間目錄條目類型。

CatalogQueryRequest

Object

搜尋的查詢。

名稱 類型 Description
continuationToken

string

下一頁的續寫標記。

延續權杖會將原始請求的 、 filter、 pageSize 和 傳遞search，因此可以單獨傳送。 該請求不得與或合併searchfilter於同一請求中;否則會回傳錯誤。
filter

string

搜尋篩選器。 隨著時間推移，可能會新增更多篩選選項。

濾波參數支援以下特性：

  • 類型：與目錄條目的屬性相匹配 type ，例如 Report、 Lakehouse、 Workspace或 。 單一濾波器最多可指定 500 個類型值，每個值最多 50 個字元。

  • WorkspaceId：包含目錄條目的工作空間的 ID。 單一濾鏡最多只能指定 12 個 WorkspaceId 值，每個值必須是有效的 GUID。

濾波參數支援以下運算子以精煉結果：

  • eq：相等;完全符合該數值。

  • ne：不平等;排除指定的值。

  • 以及：邏輯與;只有當所有條件都成立時才匹配。

  • 或：邏輯或;如果符合任何條件，則為匹配。

  • （ ）： 括號;群組表達式以定義邏輯階層。
pageSize

integer

需要退還的頁面大小。 頁面大小必須介於1到1000之間。 預設為 50。
search

string

搜尋的文字查詢。 此欄位支援在 CatalogEntry 的顯示名稱、工作區顯示名稱及描述中搜尋。

搜尋欄位支援以下運算子：

  • “ ” ： 雙引號;將附上的詞彙精確匹配。

  • * ：星號;萬用卡匹配零個或多個字元。

  • ? ：問號;萬用卡匹配單一角色。

  • & & ： 雙&符號;必須要求所有搜尋詞。

  • 底線被視為搜尋詞的一部分;不需要逃跑。

  • 其他特殊字元則被忽略，並視為分隔符。

CatalogQueryResponse

Object

搜尋結果。

名稱 類型 Description
continuationToken

string

下一頁的續作代幣。
value CatalogEntry[]:

目錄條目列表

CatalogWorkspace

Object

目錄條目的工作區。

名稱 類型 Description
displayName

string

工作區的顯示名稱。
id

string (uuid)

工作區的 ID。

ErrorParameter

Object

一個結構化參數，提供關於錯誤的額外機器可讀上下文。

名稱 類型 Description
message

string

一個人類可讀的參數意義描述。
name

string

參數識別碼。
value

string

這是參數值。

ErrorRelatedResource

Object

錯誤相關的資源詳細資料物件。

名稱 類型 Description
resourceId

string

發生錯誤的資源識別碼。
resourceType

string

發生錯誤的資源類型。

ErrorResponse

Object

錯誤回應。

名稱 類型 Description
errorCode

string

提供錯誤狀況相關信息的特定標識碼，允許服務與其使用者之間的標準化通訊。
isRetriable

boolean

若屬實，請求可重新嘗試。 如果有延遲，請使用 Retry-After 回應標頭來判斷延遲。
message

string

以人類可讀格式呈現的錯誤訊息。
moreDetails

ErrorResponseDetails[]

其他錯誤詳情的清單。
parameters

ErrorParameter[]

結構化參數提供更多機器可讀的錯誤上下文。
relatedResource

ErrorRelatedResource

與錯誤相關的資源詳情。
requestId

string (uuid)

與錯誤相關聯的要求識別碼。

ErrorResponseDetails

Object

錯誤回應的細節。

名稱 類型 Description
errorCode

string

提供錯誤狀況相關信息的特定標識碼，允許服務與其使用者之間的標準化通訊。
message

string

以人類可讀格式呈現的錯誤訊息。
parameters

ErrorParameter[]

結構化參數提供更多機器可讀的錯誤上下文。
relatedResource

ErrorRelatedResource

與錯誤相關的資源詳情。

ItemCatalogEntry

Object

Fabric 項目的目錄中繼資料表示。

名稱 類型 Description
catalogEntryType string:

FabricItem

目錄條目類型。
description

string

目錄條目的描述。
displayName

string

目錄條目顯示名稱。
hierarchy

ItemCatalogEntryHierarchy

目錄條目的層級。
id

string (uuid)

目錄條目的objectID。
type

ItemType

Fabric 項目類型。

ItemCatalogEntryHierarchy

Object

是 Fabric 資料架構中該項目的直接祖先。 僅回傳適用的等級。

名稱 類型 Description
workspace

CatalogWorkspace

就是包含該物品的工作區。

ItemType

列舉型別

項目的類型。 可能會隨著時間新增其他項目類型。

值 Description
Dashboard

PowerBI 儀錶板。
Report

PowerBI 報表。
SemanticModel

PowerBI 語意模型。
PaginatedReport

PowerBI 編頁報表。
Datamart

PowerBI datamart。
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

倉儲快照集。
DigitalTwinBuilder

DigitalTwinBuilder。
DigitalTwinBuilderFlow

數字對應項產生器流程。
MirroredAzureDatabricksCatalog

鏡像的 Azure databricks 目錄。
Map

一張地圖。
AnomalyDetector

異常偵測器。
UserDataFunction

使用者資料函數。
GraphModel

GraphModel 的 GraphModel。
GraphQuerySet

圖形 QuerySet。
SnowflakeDatabase

一個 Snowflake 資料庫，用來儲存由 Snowflake 帳號建立的 Iceberg 表格。
OperationsAgent

一個行動特工。
CosmosDBDatabase

一個 Cosmos 資料庫。
Ontology

一個本體論。
EventSchemaSet

一個事件結構集。
DataAgent

一個資料代理人。
MirroredCatalog

鏡像目錄。
PolicySet

一套政策集。
AppBackend

一個 AppBackend。
OrgApp

一個組織應用程式。
OrgAppAudience

一個組織應用程式的受眾。
DataBuildToolJob

一個 DataBuildToolJob。
AzureDatabricksStorage

A OneLake backed storage item for Azure Databricks.
Plan

一個計畫。
Monitoring

一個監控物品。
DeploymentPlan

部署計畫。
ShareSubscription

一份股票訂閱。
Share

一份。
MirroredOneLake

一個鏡像的 OneLake 產品。

WorkspaceCatalogEntry

Object

Fabric 工作區的目錄元資料表示。

名稱 類型 Description
catalogEntryType string:

Workspace

目錄條目類型。
description

string

目錄條目的描述。
displayName

string

目錄條目顯示名稱。
id

string (uuid)

目錄條目的objectID。
type

WorkspaceCatalogEntryType

目錄條目類型。 總是 Workspace 用在工作區目錄條目上。

WorkspaceCatalogEntryType

列舉型別

該類型在工作區目錄中回報。 可能會隨著時間新增其他 WorkspaceCatalogEntryType 類型。

值 Description
Workspace

工作區。