Catalog - Search

Serviço:
Core
Versão da API:
v1

A API de Pesquisa de Catálogo permite a descoberta programática das entradas do catálogo OneLake entre espaços de trabalho. Suporta pesquisa entre espaços de trabalho sobre metadados de catálogo e devolve resultados filtrados para entradas a que o principal chamador está autorizado a aceder. Os resultados da pesquisa incluem identificadores estáveis que se destinam a ser usados com APIs Fabric complementares para obter detalhes adicionais ou executar ações suportadas.

Observação

A pesquisa por catálogo está atualmente em Pré-visualização (saiba mais).

Uma Entrada de Catálogo é uma representação de metadados descobrível de uma entidade Microsoft Fabric, atualmente destinada a itens de espaço de trabalho. As entradas de catálogo destinam-se apenas à descoberta de metadados e não concedem acesso a dados subjacentes ou ao conteúdo dos itens.

Permissions

O chamador só pode descobrir entradas de catálogo para espaços de trabalho e itens a que está autorizado a aceder.

Escopos delegados necessários

Catálogo.Lido.Todos

Limitações

  • continuationToken não deve ser combinado com search ou filter. O token já transporta esses valores do pedido de origem.

  • pageSize Deve estar entre 1 e 1000.

Identidades suportadas pelo Entra da Microsoft

Esta API suporta as identidades do Microsoft listadas nesta secção.

Identidade Suporte
User Sim
Entidade de serviço e identidades geridas Sim

Interface

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

Corpo do Pedido

Nome Tipo Descrição
continuationToken

string

O token de continuação para a página seguinte.

Um token de continuação transporta adiante o search, filter, e pageSize do pedido original, pelo que pode ser enviado por si só. Não pode ser combinado com search ou filter no mesmo pedido; fazê-lo devolve um erro.
filter

string

O filtro para a pesquisa. Podem ser adicionadas opções adicionais de filtro ao longo do tempo.

O parâmetro de filtro suporta as seguintes propriedades:

  • Tipo: Corresponde à type propriedade de uma entrada de catálogo, por exemplo Report, Lakehouse, ou Workspace. Um único filtro pode especificar no máximo 500 valores de Tipo, cada um com até 50 caracteres.

  • WorkspaceId: O ID do espaço de trabalho que contém a entrada do catálogo. Um único filtro pode especificar no máximo 12 valores WorkspaceId, cada um dos quais deve ser um GUID válido.

O parâmetro do filtro suporta os seguintes operadores para refinar os resultados:

  • eq: Igual; corresponde ao valor exato.

  • ne: Não é igual; exclui o valor especificado.

  • e: E lógico; corresponde apenas se todas as condições forem verdadeiras.

  • ou: Lógica OU; corresponde se alguma das condições for verdadeira.

  • ( ): Parênteses; agrupa expressões para definir hierarquia lógica.
pageSize

integer

O tamanho da página que precisa de ser devolvido. O tamanho da página deve estar entre 1 e 1000. O padrão é 50.
search

string

A consulta de texto para a pesquisa. Este campo suporta a pesquisa através do nome de visualização, nome de apresentação do espaço de trabalho e descrição da Entrada de Catálogo.

O campo de pesquisa suporta os seguintes operadores:

  • " " : Aspas duplas; corresponde às palavras anexas como uma frase exata.

  • * : Asterisco; coringa com zero ou mais caracteres.

  • ? : Ponto de interrogação; coringa que corresponde a um único carácter.

  • && : Ampersands duplos; requer todos os termos de pesquisa.

  • Os sublinhados são tratados como parte de um termo de pesquisa; não é necessário escapar.

  • Outras personagens especiais são ignoradas e tratadas como separadores.

Respostas

Nome Tipo Descrição
200 OK

CatalogQueryResponse

OK
429 Too Many Requests

ErrorResponse

O limite de tarifa de serviço foi ultrapassado. O servidor devolve um Retry-After cabeçalho que indica, em segundos, quanto tempo o cliente deve esperar antes de enviar pedidos adicionais.

Cabeçalhos

Retry-After: integer
Other Status Codes

ErrorResponse

Códigos de erro comuns:

  • InvalidRequest - O corpo do pedido não foi fornecido, ou é inválido.

  • InvalidSearch - O search valor não pôde ser analisado.

  • InvalidFilter - O filter valor não pode ser analisado, ou um valor do filtro está mal formado ou excede o seu comprimento máximo.

  • InvalidFilterProperty - A filter referência a uma propriedade que não é suportada.

  • FilterTooManyValues - Especifica filter mais valores para uma propriedade do que essa propriedade permite.

  • FilterNotSupported - Filtragem não é suportada.

  • ConflitingFilterParameters - continuationToken foi combinado com search ou filter.

  • InvalidPageSize - pageSize está fora do intervalo de 1 a 1000.

  • InvalidContinuationToken - O continuationToken não é válido.

  • ContinuationTokenTooLong - O continuationToken ultrapassa o comprimento máximo.

  • TypeNotFound - Refere-se filter a um tipo de item que não existe.

  • Não autorizado - Autenticação ausente ou inválida

  • Erro interno do servidor - Falha inesperada do serviço.

Exemplos

Search example
Search within a workspace example

Search example

Pedido de amostra

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

Resposta da amostra

Código de estado:
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

Pedido de amostra

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
}

Resposta da amostra

Código de estado:
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..."
}

Definições

Nome Descrição
CatalogEntryType

O tipo de entrada do catálogo. Tipos de CatalogEntryType adicionais podem ser adicionados ao longo do tempo.
CatalogQueryRequest

A consulta para a pesquisa.
CatalogQueryResponse

Os resultados da pesquisa.
CatalogWorkspace

O espaço de trabalho para a entrada do catálogo.
ErrorParameter

Um parâmetro estruturado que fornece contexto adicional legível por máquina sobre um erro.
ErrorRelatedResource

Os detalhes do objeto de recurso relacionado ao erro.
ErrorResponse

A resposta de erro.
ErrorResponseDetails

Os detalhes do erro na resposta.
ItemCatalogEntry

A representação de metadados do catálogo de um item Fabric.
ItemCatalogEntryHierarchy

Os antepassados imediatos do item na arquitetura de dados da Fabric. Apenas os níveis aplicáveis são devolvidos.
ItemType

O tipo do item. Tipos de itens adicionais podem ser adicionados ao longo do tempo.
WorkspaceCatalogEntry

A representação de metadados de catálogo de um espaço de trabalho Fabric.
WorkspaceCatalogEntryType

O tipo reportado numa entrada de catálogo de espaço de trabalho. Tipos de WorkspaceCatalogEntryType adicionais podem ser adicionados ao longo do tempo.

CatalogEntryType

Enumeração

O tipo de entrada do catálogo. Tipos de CatalogEntryType adicionais podem ser adicionados ao longo do tempo.

Valor Descrição
FabricItem

Um tipo de entrada para o catálogo de artigos de tecido.
Workspace

Um tipo de entrada de catálogo de espaço de trabalho.

CatalogQueryRequest

Object

A consulta para a pesquisa.

Nome Tipo Descrição
continuationToken

string

O token de continuação para a página seguinte.

Um token de continuação transporta adiante o search, filter, e pageSize do pedido original, pelo que pode ser enviado por si só. Não pode ser combinado com search ou filter no mesmo pedido; fazê-lo devolve um erro.
filter

string

O filtro para a pesquisa. Podem ser adicionadas opções adicionais de filtro ao longo do tempo.

O parâmetro de filtro suporta as seguintes propriedades:

  • Tipo: Corresponde à type propriedade de uma entrada de catálogo, por exemplo Report, Lakehouse, ou Workspace. Um único filtro pode especificar no máximo 500 valores de Tipo, cada um com até 50 caracteres.

  • WorkspaceId: O ID do espaço de trabalho que contém a entrada do catálogo. Um único filtro pode especificar no máximo 12 valores WorkspaceId, cada um dos quais deve ser um GUID válido.

O parâmetro do filtro suporta os seguintes operadores para refinar os resultados:

  • eq: Igual; corresponde ao valor exato.

  • ne: Não é igual; exclui o valor especificado.

  • e: E lógico; corresponde apenas se todas as condições forem verdadeiras.

  • ou: Lógica OU; corresponde se alguma das condições for verdadeira.

  • ( ): Parênteses; agrupa expressões para definir hierarquia lógica.
pageSize

integer

O tamanho da página que precisa de ser devolvido. O tamanho da página deve estar entre 1 e 1000. O padrão é 50.
search

string

A consulta de texto para a pesquisa. Este campo suporta a pesquisa através do nome de visualização, nome de apresentação do espaço de trabalho e descrição da Entrada de Catálogo.

O campo de pesquisa suporta os seguintes operadores:

  • " " : Aspas duplas; corresponde às palavras anexas como uma frase exata.

  • * : Asterisco; coringa com zero ou mais caracteres.

  • ? : Ponto de interrogação; coringa que corresponde a um único carácter.

  • && : Ampersands duplos; requer todos os termos de pesquisa.

  • Os sublinhados são tratados como parte de um termo de pesquisa; não é necessário escapar.

  • Outras personagens especiais são ignoradas e tratadas como separadores.

CatalogQueryResponse

Object

Os resultados da pesquisa.

Nome Tipo Descrição
continuationToken

string

O ContinuationToken para a página seguinte.
value CatalogEntry[]:

Uma lista de entradas do catálogo

CatalogWorkspace

Object

O espaço de trabalho para a entrada do catálogo.

Nome Tipo Descrição
displayName

string

O nome de exibição do espaço de trabalho.
id

string (uuid)

A ID do espaço de trabalho.

ErrorParameter

Object

Um parâmetro estruturado que fornece contexto adicional legível por máquina sobre um erro.

Nome Tipo Descrição
message

string

Uma descrição legível para humanos do significado do parâmetro.
name

string

O identificador de parâmetro.
value

string

O valor do parâmetro.

ErrorRelatedResource

Object

Os detalhes do objeto de recurso relacionado ao erro.

Nome Tipo Descrição
resourceId

string

O ID do recurso envolvido no erro.
resourceType

string

O tipo de recurso envolvido no erro.

ErrorResponse

Object

A resposta de erro.

Nome Tipo Descrição
errorCode

string

Um identificador específico que fornece informações sobre uma condição de erro, permitindo uma comunicação padronizada entre nosso serviço e seus usuários.
isRetriable

boolean

Quando confirmado, o pedido pode ser retentado. Use o Retry-After cabeçalho de resposta para determinar o atraso, se disponível.
message

string

Uma representação legível por humanos do erro.
moreDetails

ErrorResponseDetails[]

Lista de detalhes de erro adicionais.
parameters

ErrorParameter[]

Parâmetros estruturados que fornecem contexto adicional legível pela máquina sobre o erro.
relatedResource

ErrorRelatedResource

Detalhes do recurso relacionado ao erro.
requestId

string (uuid)

ID da solicitação associada ao erro.

ErrorResponseDetails

Object

Os detalhes do erro na resposta.

Nome Tipo Descrição
errorCode

string

Um identificador específico que fornece informações sobre uma condição de erro, permitindo uma comunicação padronizada entre nosso serviço e seus usuários.
message

string

Uma representação legível por humanos do erro.
parameters

ErrorParameter[]

Parâmetros estruturados que fornecem contexto adicional legível pela máquina sobre o erro.
relatedResource

ErrorRelatedResource

Detalhes do recurso relacionado ao erro.

ItemCatalogEntry

Object

A representação de metadados do catálogo de um item Fabric.

Nome Tipo Descrição
catalogEntryType string:

FabricItem

O tipo de entrada do catálogo.
description

string

A descrição da entrada do catálogo.
displayName

string

O nome de exibição da entrada do catálogo.
hierarchy

ItemCatalogEntryHierarchy

A hierarquia da entrada do catálogo.
id

string (uuid)

O objectId da entrada do catálogo.
type

ItemType

O tipo de item Malha.

ItemCatalogEntryHierarchy

Object

Os antepassados imediatos do item na arquitetura de dados da Fabric. Apenas os níveis aplicáveis são devolvidos.

Nome Tipo Descrição
workspace

CatalogWorkspace

O espaço de trabalho que contém o item.

ItemType

Enumeração

O tipo do item. Tipos de itens adicionais podem ser adicionados ao longo do tempo.

Valor Descrição
Dashboard

Painel do PowerBI.
Report

Relatório do PowerBI.
SemanticModel

Modelo semântico do PowerBI.
PaginatedReport

Relatório paginado do PowerBI.
Datamart

Datamart do PowerBI.
Lakehouse

Uma casa no lago.
Eventhouse

Uma casa de eventos.
Environment

Um ambiente.
KQLDatabase

Um banco de dados KQL.
KQLQueryset

Um conjunto de consultas KQL.
KQLDashboard

Um painel KQL.
DataPipeline

Um pipeline de dados.
Notebook

Um caderno.
SparkJobDefinition

Uma definição de trabalho de faísca.
MLExperiment

Uma experiência de aprendizagem automática.
MLModel

Um modelo de aprendizagem automática.
Warehouse

Um armazém.
Eventstream

Um fluxo de eventos.
SQLEndpoint

Um ponto de extremidade SQL.
MirroredWarehouse

Um armazém espelhado.
MirroredDatabase

Um banco de dados espelhado.
Reflex

Um reflexo.
GraphQLApi

Uma API para o item GraphQL.
MountedDataFactory

Um MountedDataFactory.
SQLDatabase

Um SQLDatabase.
CopyJob

Um trabalho de cópia.
VariableLibrary

Uma VariableLibrary.
Dataflow

Um fluxo de dados.
ApacheAirflowJob

Um ApacheAirflowJob.
WarehouseSnapshot

Um instantâneo do Warehouse.
DigitalTwinBuilder

Um DigitalTwinBuilder.
DigitalTwinBuilderFlow

Um fluxo de construtor de gêmeos digitais.
MirroredAzureDatabricksCatalog

Um catálogo de databricks azure espelhado.
Map

Um mapa.
AnomalyDetector

Um detetor de anomalias.
UserDataFunction

Uma função de dados do usuário.
GraphModel

Um GraphModel.
GraphQuerySet

Um Graph QuerySet.
SnowflakeDatabase

Uma base de dados Snowflake para armazenar tabelas Iceberg criadas a partir da conta Snowflake.
OperationsAgent

Um Agente de Operações.
CosmosDBDatabase

Uma base de dados Cosmos DB.
Ontology

Uma ontologia.
EventSchemaSet

Um EventoSchemaSet.
DataAgent

Um DataAgent.
MirroredCatalog

Um Catálogo Espelhado.
PolicySet

Um Conjunto de Políticas.
AppBackend

Um AppBackend.
OrgApp

Uma aplicação de organização.
OrgAppAudience

Uma audiência de Org App.
DataBuildToolJob

Um DataBuildToolJob.
AzureDatabricksStorage

Um item de armazenamento apoiado por OneLake para Azure Databricks.
Plan

Um plano.

WorkspaceCatalogEntry

Object

A representação de metadados de catálogo de um espaço de trabalho Fabric.

Nome Tipo Descrição
catalogEntryType string:

Workspace

O tipo de entrada do catálogo.
description

string

A descrição da entrada do catálogo.
displayName

string

O nome de exibição da entrada do catálogo.
id

string (uuid)

O objectId da entrada do catálogo.
type

WorkspaceCatalogEntryType

O tipo de entrada do catálogo. Sempre Workspace para entradas de catálogo de espaços de trabalho.

WorkspaceCatalogEntryType

Enumeração

O tipo reportado numa entrada de catálogo de espaço de trabalho. Tipos de WorkspaceCatalogEntryType adicionais podem ser adicionados ao longo do tempo.

Valor Descrição
Workspace

Um espaço de trabalho.