Catalog - Search

Service:: Core

Versione API:: v1

L'API Ricerca catalogo consente l'individuazione a livello di codice delle voci del catalogo OneLake tra aree di lavoro. Supporta la ricerca tra aree di lavoro sui metadati del catalogo e restituisce i risultati filtrati per le voci a cui l'entità chiamante è autorizzata ad accedere. I risultati della ricerca includono identificatori stabili che devono essere usati con api di Infrastruttura complementari per recuperare dettagli aggiuntivi o eseguire azioni supportate.

Annotazioni

La ricerca del catalogo è attualmente disponibile in anteprima (altre informazioni).

CatalogEntry è una rappresentazione di metadati individuabile di un'entità di Microsoft Fabric, attualmente con ambito per gli elementi dell'area di lavoro. Le voci del catalogo sono destinate solo all'individuazione dei metadati e non concedono l'accesso ai dati o al contenuto dell'elemento sottostante.

Permissions

Il chiamante può individuare solo le voci del catalogo per le aree di lavoro e gli elementi a cui il chiamante è autorizzato ad accedere.

Ambiti delegati obbligatori

Catalog.Read.All

Limitazioni

continuationToken non deve essere combinato con search o filter. Il token contiene già tali valori dalla richiesta di origine.
pageSize deve essere compreso tra 1 e 1000.

Identità supportate da Microsoft Entra

Questa API supporta le identità di Microsoft elencate in questa sezione.

Identità	Support
User	Sì
Principale del servizio e Identità gestite	Sì

Interfaccia

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

Corpo della richiesta

Nome	Tipo	Descrizione
continuationToken	string	Token di continuazione per la pagina successiva. Un token di continuazione inoltra , `searchfilter`e `pageSize` della richiesta originale, quindi può essere inviato autonomamente. Non deve essere combinato con `search` o `filter` nella stessa richiesta. In questo modo viene restituito un errore.
filter	string	Filtro per la ricerca. È possibile aggiungere altre opzioni di filtro nel tempo. Il parametro filter supporta le proprietà seguenti: Tipo: corrisponde alla `type` proprietà di una voce del catalogo, ad esempio `Report`, `Lakehouse`o `Workspace`. Un singolo filtro può specificare al massimo 500 valori di tipo, ognuno con lunghezza massima di 50 caratteri. WorkspaceId: ID dell'area di lavoro che contiene la voce del catalogo. Un singolo filtro può specificare al massimo 12 valori WorkspaceId, ognuno dei quali deve essere un GUID valido. Il parametro filter supporta gli operatori seguenti per perfezionare i risultati: eq: Equals; corrisponde al valore esatto. ne: Diverso da; esclude il valore specificato. e: AND logico; corrisponde solo se tutte le condizioni sono vere. oppure: OR logico; corrisponde se una delle condizioni è vera. ( ): parentesi; raggruppa le espressioni per definire la gerarchia logica.
pageSize	integer	Dimensioni della pagina che devono essere restituite. Le dimensioni della pagina devono essere comprese tra 1 e 1000. Il valore predefinito è 50.
search	string	Query di testo per la ricerca. Questo campo supporta la ricerca tra il nome visualizzato, il nome visualizzato dell'area di lavoro e la descrizione di CatalogEntry. Il campo di ricerca supporta gli operatori seguenti: " " : virgolette doppie; corrisponde alle parole racchiuse come frase esatta. * : Asterisco; caratteri jolly corrispondenti a zero o più caratteri. ? : punto interrogativo; carattere jolly corrispondente a un singolo carattere. & Doppie e commerciale; richiede ogni termine di ricerca. I caratteri di sottolineatura vengono trattati come parte di un termine di ricerca; non è necessaria alcuna escape. Gli altri caratteri speciali vengono ignorati e trattati come separatori.

Risposte

Nome Tipo Descrizione

200 OK

Nome	Tipo	Descrizione
200 OK	CatalogQueryResponse	Va bene
429 Too Many Requests	ErrorResponse	È stato superato il limite di velocità del servizio. Il server restituisce un'intestazione `Retry-After` che indica, in secondi, per quanto tempo il client deve attendere prima di inviare richieste aggiuntive. Intestazioni Retry-After: integer
Other Status Codes	ErrorResponse	Codici di errore comuni: InvalidRequest: il corpo della richiesta non è stato specificato o non è valido in caso contrario. InvalidSearch: non è stato possibile analizzare il `search` valore. InvalidFilter: non è stato possibile analizzare l'oggetto `filter` oppure un valore di filtro non è valido o supera la lunghezza massima. InvalidFilterProperty: fa `filter` riferimento a una proprietà non supportata. FilterTooManyValues: `filter` specifica più valori per una proprietà rispetto a quella consentita. FilterNotSupported: il filtro non è supportato. ConflictingFilterParameters : `continuationToken` è stato combinato con `search` o `filter`. InvalidPageSize: `pageSize` non è compreso nell'intervallo compreso tra 1 e 1000. InvalidContinuationToken: l'oggetto `continuationToken` non è valido. ContinuationTokenTooLong: `continuationToken` supera la lunghezza massima. TypeNotFound: `filter` fa riferimento a un tipo di elemento che non esiste. Non autorizzato - Autenticazione mancante o non valida Errore interno del server - Errore imprevisto del servizio.

CatalogQueryResponse

Va bene

429 Too Many Requests

ErrorResponse

È stato superato il limite di velocità del servizio. Il server restituisce un'intestazione Retry-After che indica, in secondi, per quanto tempo il client deve attendere prima di inviare richieste aggiuntive.

Intestazioni

Retry-After: integer

Other Status Codes

ErrorResponse

Codici di errore comuni:

InvalidRequest: il corpo della richiesta non è stato specificato o non è valido in caso contrario.
InvalidSearch: non è stato possibile analizzare il search valore.
InvalidFilter: non è stato possibile analizzare l'oggetto filter oppure un valore di filtro non è valido o supera la lunghezza massima.
InvalidFilterProperty: fa filter riferimento a una proprietà non supportata.
FilterTooManyValues: filter specifica più valori per una proprietà rispetto a quella consentita.
FilterNotSupported: il filtro non è supportato.
ConflictingFilterParameters : continuationToken è stato combinato con search o filter.
InvalidPageSize: pageSize non è compreso nell'intervallo compreso tra 1 e 1000.
InvalidContinuationToken: l'oggetto continuationToken non è valido.
ContinuationTokenTooLong: continuationToken supera la lunghezza massima.
TypeNotFound: filter fa riferimento a un tipo di elemento che non esiste.
Non autorizzato - Autenticazione mancante o non valida
Errore interno del server - Errore imprevisto del servizio.

Esempio

Search example

Search within a workspace example

Search example

Esempio di richiesta

HTTP

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'"
}

Risposta di esempio

Codice di stato:: 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

Esempio di richiesta

HTTP

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
}

Risposta di esempio

Codice di stato:: 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..."
}

Definizioni

Nome	Descrizione
CatalogEntryType	Tipo di voce del catalogo. È possibile aggiungere altri tipi di `CatalogEntryType` nel tempo.
CatalogQueryRequest	Query per la ricerca.
CatalogQueryResponse	Risultati della ricerca.
CatalogWorkspace	Area di lavoro per la voce del catalogo.
ErrorParameter	Parametro strutturato che fornisce un contesto aggiuntivo leggibile dal computer relativo a un errore.
ErrorRelatedResource	Oggetto dei dettagli della risorsa relativo all'errore.
ErrorResponse	Risposta di errore.
ErrorResponseDetails	Dettagli della risposta di errore.
ItemCatalogEntry	Rappresentazione dei metadati del catalogo di un elemento Fabric.
ItemCatalogEntryHierarchy	Predecessori immediati dell'elemento nell'architettura dei dati di Fabric. Vengono restituiti solo i livelli applicabili.
ItemType	Tipo dell'elemento. È possibile aggiungere altri tipi di elemento nel tempo.
WorkspaceCatalogEntry	Rappresentazione dei metadati del catalogo di un'area di lavoro Fabric.
WorkspaceCatalogEntryType	Tipo riportato in una voce del catalogo dell'area di lavoro. È possibile aggiungere altri tipi di `WorkspaceCatalogEntryType` nel tempo.

CatalogEntryType

Enumerazione

Tipo di voce del catalogo. È possibile aggiungere altri tipi di CatalogEntryType nel tempo.

Valore	Descrizione
FabricItem	Tipo di voce del catalogo di elementi di Fabric.
Workspace	Tipo di voce del catalogo dell'area di lavoro.

CatalogQueryRequest

Oggetto

Query per la ricerca.

Nome	Tipo	Descrizione
continuationToken	string	Token di continuazione per la pagina successiva. Un token di continuazione inoltra , `searchfilter`e `pageSize` della richiesta originale, quindi può essere inviato autonomamente. Non deve essere combinato con `search` o `filter` nella stessa richiesta. In questo modo viene restituito un errore.
filter	string	Filtro per la ricerca. È possibile aggiungere altre opzioni di filtro nel tempo. Il parametro filter supporta le proprietà seguenti: Tipo: corrisponde alla `type` proprietà di una voce del catalogo, ad esempio `Report`, `Lakehouse`o `Workspace`. Un singolo filtro può specificare al massimo 500 valori di tipo, ognuno con lunghezza massima di 50 caratteri. WorkspaceId: ID dell'area di lavoro che contiene la voce del catalogo. Un singolo filtro può specificare al massimo 12 valori WorkspaceId, ognuno dei quali deve essere un GUID valido. Il parametro filter supporta gli operatori seguenti per perfezionare i risultati: eq: Equals; corrisponde al valore esatto. ne: Diverso da; esclude il valore specificato. e: AND logico; corrisponde solo se tutte le condizioni sono vere. oppure: OR logico; corrisponde se una delle condizioni è vera. ( ): parentesi; raggruppa le espressioni per definire la gerarchia logica.
pageSize	integer	Dimensioni della pagina che devono essere restituite. Le dimensioni della pagina devono essere comprese tra 1 e 1000. Il valore predefinito è 50.
search	string	Query di testo per la ricerca. Questo campo supporta la ricerca tra il nome visualizzato, il nome visualizzato dell'area di lavoro e la descrizione di CatalogEntry. Il campo di ricerca supporta gli operatori seguenti: " " : virgolette doppie; corrisponde alle parole racchiuse come frase esatta. * : Asterisco; caratteri jolly corrispondenti a zero o più caratteri. ? : punto interrogativo; carattere jolly corrispondente a un singolo carattere. & Doppie e commerciale; richiede ogni termine di ricerca. I caratteri di sottolineatura vengono trattati come parte di un termine di ricerca; non è necessaria alcuna escape. Gli altri caratteri speciali vengono ignorati e trattati come separatori.

CatalogQueryResponse

Oggetto

Risultati della ricerca.

Nome	Tipo	Descrizione
continuationToken	string	ContinuationToken per la pagina successiva.
value	CatalogEntry[]: ItemCatalogEntry[] WorkspaceCatalogEntry[]	Elenco di voci del catalogo

CatalogWorkspace

Oggetto

Area di lavoro per la voce del catalogo.

Nome	Tipo	Descrizione
displayName	string	Nome visualizzato dell'area di lavoro.
id	string (uuid)	ID dell'area di lavoro.

ErrorParameter

Oggetto

Parametro strutturato che fornisce un contesto aggiuntivo leggibile dal computer relativo a un errore.

Nome	Tipo	Descrizione
message	string	Descrizione leggibile del significato del parametro.
name	string	L'identificatore dei parametri.
value	string	Valore del parametro.

ErrorRelatedResource

Oggetto

Oggetto dei dettagli della risorsa relativo all'errore.

Nome	Tipo	Descrizione
resourceId	string	ID risorsa coinvolto nell'errore.
resourceType	string	Tipo della risorsa coinvolta nell'errore.

ErrorResponse

Oggetto

Risposta di errore.

Nome	Tipo	Descrizione
errorCode	string	Identificatore specifico che fornisce informazioni su una condizione di errore, consentendo la comunicazione standardizzata tra il servizio e i relativi utenti.
isRetriable	boolean	Se true, la richiesta può essere ritentata. Usare l'intestazione della `Retry-After` risposta per determinare il ritardo, se disponibile.
message	string	Rappresentazione leggibile dell'errore.
moreDetails	ErrorResponseDetails[]	Elenco di dettagli aggiuntivi sull'errore.
parameters	ErrorParameter[]	Parametri strutturati che forniscono un contesto aggiuntivo leggibile dal computer sull'errore.
relatedResource	ErrorRelatedResource	Dettagli della risorsa correlati all'errore.
requestId	string (uuid)	ID della richiesta associata all'errore.

ErrorResponseDetails

Oggetto

Dettagli della risposta di errore.

Nome	Tipo	Descrizione
errorCode	string	Identificatore specifico che fornisce informazioni su una condizione di errore, consentendo la comunicazione standardizzata tra il servizio e i relativi utenti.
message	string	Rappresentazione leggibile dell'errore.
parameters	ErrorParameter[]	Parametri strutturati che forniscono un contesto aggiuntivo leggibile dal computer sull'errore.
relatedResource	ErrorRelatedResource	Dettagli della risorsa correlati all'errore.

ItemCatalogEntry

Oggetto

Rappresentazione dei metadati del catalogo di un elemento Fabric.

Nome	Tipo	Descrizione
catalogEntryType	string: FabricItem	Tipo di voce del catalogo.
description	string	Descrizione della voce del catalogo.
displayName	string	Nome visualizzato della voce del catalogo.
hierarchy	ItemCatalogEntryHierarchy	Gerarchia della voce del catalogo.
id	string (uuid)	ObjectId della voce del catalogo.
type	ItemType	Tipo di elemento Fabric.

ItemCatalogEntryHierarchy

Oggetto

Predecessori immediati dell'elemento nell'architettura dei dati di Fabric. Vengono restituiti solo i livelli applicabili.

Nome	Tipo	Descrizione
workspace	CatalogWorkspace	Area di lavoro che contiene l'elemento.

ItemType

Enumerazione

Tipo dell'elemento. È possibile aggiungere altri tipi di elemento nel tempo.

Valore	Descrizione
Dashboard	Dashboard di Power BI.
Report	Report di Power BI.
SemanticModel	Modello semantico di PowerBI.
PaginatedReport	Report impaginato di Power BI.
Datamart	Datamart di PowerBI.
Lakehouse	Una lakehouse.
Eventhouse	Una casa eventi.
Environment	Un ambiente.
KQLDatabase	Un database KQL.
KQLQueryset	Set di query KQL.
KQLDashboard	Dashboard KQL.
DataPipeline	Una pipeline di dati.
Notebook	Un notebook.
SparkJobDefinition	Definizione di processo Spark.
MLExperiment	Esperimento di Machine Learning.
MLModel	Modello di Machine Learning.
Warehouse	Un magazzino.
Eventstream	Flusso di eventi.
SQLEndpoint	Endpoint SQL.
MirroredWarehouse	Magazzino con mirroring.
MirroredDatabase	Database con mirroring.
Reflex	Un riflesso.
GraphQLApi	API per l'elemento GraphQL.
MountedDataFactory	Oggetto MountedDataFactory.
SQLDatabase	A SQLDatabase.
CopyJob	Processo di copia.
VariableLibrary	VariabileLibrary.
Dataflow	Flusso di dati.
ApacheAirflowJob	An ApacheAirflowJob.
WarehouseSnapshot	Uno snapshot del warehouse.
DigitalTwinBuilder	A DigitalTwinBuilder.
DigitalTwinBuilderFlow	Flusso di Generatore di gemelli digitali.
MirroredAzureDatabricksCatalog	Catalogo di Azure databricks con mirroring.
Map	Una mappa.
AnomalyDetector	Rilevamento anomalie.
UserDataFunction	Funzione dati utente.
GraphModel	A GraphModel.
GraphQuerySet	Oggetto Graph QuerySet.
SnowflakeDatabase	Un database Snowflake per archiviare le tabelle Iceberg create dall'account Snowflake.
OperationsAgent	Oggetto OperationsAgent.
CosmosDBDatabase	Un database Cosmos DB.
Ontology	Ontologia.
EventSchemaSet	An EventSchemaSet.
DataAgent	Oggetto DataAgent.
MirroredCatalog	Oggetto MirroredCatalog.
PolicySet	Un oggetto PolicySet.
AppBackend	An AppBackend.
OrgApp	Un'app dell'organizzazione.
OrgAppAudience	Gruppo di destinatari di un'app dell'organizzazione.
DataBuildToolJob	A DataBuildToolJob.
AzureDatabricksStorage	Elemento di archiviazione supportato da OneLake per Azure Databricks.
Plan	Un piano.
Monitoring	Elemento Monitoraggio.
DeploymentPlan	Piano di distribuzione.

WorkspaceCatalogEntry

Oggetto

Rappresentazione dei metadati del catalogo di un'area di lavoro Fabric.

Nome	Tipo	Descrizione
catalogEntryType	string: Workspace	Tipo di voce del catalogo.
description	string	Descrizione della voce del catalogo.
displayName	string	Nome visualizzato della voce del catalogo.
id	string (uuid)	ObjectId della voce del catalogo.
type	WorkspaceCatalogEntryType	Tipo di voce del catalogo. Sempre `Workspace` per le voci del catalogo dell'area di lavoro.

WorkspaceCatalogEntryType

Enumerazione

Tipo riportato in una voce del catalogo dell'area di lavoro. È possibile aggiungere altri tipi di WorkspaceCatalogEntryType nel tempo.

Valore	Descrizione
Workspace	Un'area di lavoro.