Items - Create Semantic Model

Serviço:: SemanticModel

Versão da API:: v1

Cria um modelo semântico no espaço de trabalho especificado.
Esta API suporta operações de longa duração (LRO).

A API suporta três modos de criação: (1) fornecer controlo definition total sobre a estrutura do modelo, (2) fornecer creationPayload URLs de tabelas OneLake para criar um modelo DirectLake, ou (3) omitir ambos para criar um modelo semântico vazio. Utilizar definition ou creationPayload. Não é possível usar os dois ao mesmo tempo.

Permissões

O chamador deve ter uma função de espaço de trabalho de colaborador . Ao criar um modelo DirectLake com um creationPayload que referencia tabelas OneLake, o chamador deve também ter acesso a cada Lakehouse ou elemento de dados de origem referenciado, incluindo quando essas fontes residem num espaço de trabalho diferente (fontes entre espaços de trabalho).

Escopos delegados necessários

SemanticModel.ReadWrite.All ou Item.ReadWrite.All

Limitações

Para criar um modelo semântico, o usuário deve ter a licença apropriada. Para mais informações, veja: Microsoft Fabric tipos de licença.

Identidades suportadas pela Microsoft Entra

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

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

Interfaz

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/semanticModels

Parâmetros do URI

Nome	Em	Obrigatório	Tipo	Descrição
workspaceId	path	True	string (uuid)	O ID do espaço de trabalho.

Corpo do Pedido

Nome	Obrigatório	Tipo	Descrição
displayName	True	string	O nome de exibição do modelo semântico. O nome para exibição deve seguir regras de nomenclatura de acordo com o tipo de item.
creationPayload		SemanticModelCreationPayload	A carga útil de criação para criar um modelo semântico sem uma definição completa. Forneça URLs de tabelas OneLake para criar um modelo DirectLake, ou omita ambos `definition` e `creationPayload` crie um modelo semântico vazio. Utilizar `definition` ou `creationPayload`. Não é possível usar os dois ao mesmo tempo.
definition		SemanticModelDefinition	A definição pública do modelo semântico. Utilizar `definition` ou `creationPayload`. Não é possível usar os dois ao mesmo tempo.
description		string	A descrição do modelo semântico. O comprimento máximo é de 256 caracteres.
folderId		string (uuid)	O ID da pasta. Se não especificado ou nulo, o modelo semântico é criado com o espaço de trabalho como sua pasta.
sensitivityLabelSettings		SensitivityLabelSettings	As definições da etiqueta de sensibilidade para o modelo semântico.

Respostas

Nome	Tipo	Descrição
201 Created	SemanticModel	Criado com sucesso
202 Accepted		Solicitação aceita, provisionamento de modelo semântico em andamento. Cabeçalhos Location: string x-ms-operation-id: string Retry-After: integer
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: ItemDisplayNameAlreadyInUse - O nome de exibição do item já é usado. CorruptedPayload - A carga fornecida está corrompida. MutuallyExclusiveProperties - Os `definition` e `creationPayload` não podem ser fornecidos ambos. InvalidOneLakeTableUrl - Um ou mais URLs de tabelas OneLake são inválidos. DuplicateTableName - Nomes duplicados de tabelas não são permitidos.

Exemplos

Create a semantic model example

Create a semantic model with OneLake tables example

Create an empty semantic model example

Create a semantic model example

Pedido de amostra

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/semanticModels

{
  "displayName": "SemanticModel 1",
  "description": "A semantic model description.",
  "definition": {
    "parts": [
      {
        "path": "model.bim",
        "payload": "ew0KICAiY29tcGF0a..GVzIjogWyBdDQogIH0NCn0=",
        "payloadType": "InlineBase64"
      },
      {
        "path": "definition.pbism",
        "payload": "ewogICJ2ZXJzaW9uI..NldHRpbmdzIjoge30KfQ==",
        "payloadType": "InlineBase64"
      },
      {
        "path": ".platform",
        "payload": "ZG90UGxhdGZvcm1CYXNlNjRTdHJpbmc=",
        "payloadType": "InlineBase64"
      }
    ]
  }
}

Resposta da amostra

Código de estado:: 201

{
  "displayName": "SemanticModel 1",
  "description": "A semantic model description.",
  "type": "SemanticModel",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "id": "5b218778-e7a5-4d73-8187-f10824047715",
  "sensitivityLabel": {
    "id": "b7b4f4d9-3f0d-4b3e-8f3d-4f6d3f4f3f4f"
  }
}

Código de estado:: 202

Location: https://api.fabric.microsoft.com/v1/operations/0acd697c-1550-43cd-b998-91bfbfbd47c6
x-ms-operation-id: 0acd697c-1550-43cd-b998-91bfbfbd47c6
Retry-After: 30

Create a semantic model with OneLake tables example

Pedido de amostra

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/semanticModels

{
  "displayName": "Sales Analytics Model",
  "description": "A semantic model connected to lakehouse tables.",
  "creationPayload": {
    "oneLakeTables": [
      "https://onelake.dfs.fabric.microsoft.com/aaaa0000-bb11-2222-33cc-444444dddddd/cccc0000-dd11-2222-33ee-444444ffffff/Tables/dim_customer",
      "https://onelake.dfs.fabric.microsoft.com/aaaa0000-bb11-2222-33cc-444444dddddd/cccc0000-dd11-2222-33ee-444444ffffff/Tables/sales/dim_product",
      "https://onelake.dfs.fabric.microsoft.com/1111aaaa-bb22-3333-44cc-555555eeeeee/2222bbbb-cc33-4444-55dd-666666ffffff/Tables/dim_region"
    ]
  }
}

Resposta da amostra

Código de estado:: 201

{
  "displayName": "Sales Analytics Model",
  "description": "A semantic model connected to lakehouse tables.",
  "type": "SemanticModel",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "id": "5b218778-e7a5-4d73-8187-f10824047715"
}

Código de estado:: 202

Location: https://api.fabric.microsoft.com/v1/operations/0acd697c-1550-43cd-b998-91bfbfbd47c6
x-ms-operation-id: 0acd697c-1550-43cd-b998-91bfbfbd47c6
Retry-After: 30

Create an empty semantic model example

Pedido de amostra

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/semanticModels

{
  "displayName": "SemanticModel 1",
  "description": "An empty semantic model."
}

Resposta da amostra

Código de estado:: 201

{
  "displayName": "SemanticModel 1",
  "description": "An empty semantic model.",
  "type": "SemanticModel",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "id": "5b218778-e7a5-4d73-8187-f10824047715"
}

Código de estado:: 202

Location: https://api.fabric.microsoft.com/v1/operations/0acd697c-1550-43cd-b998-91bfbfbd47c6
x-ms-operation-id: 0acd697c-1550-43cd-b998-91bfbfbd47c6
Retry-After: 30

Definições

Nome	Descrição
CreateSemanticModelRequest	Crie carga útil de solicitação de modelo semântico.
EntireTenantPrincipal	Representa um principal inquilino
ErrorParameter	Um parâmetro estruturado que fornece contexto adicional legível por máquina sobre um erro.
ErrorRelatedResource	O objeto de detalhes do recurso relacionado ao erro.
ErrorResponse	A resposta de erro.
ErrorResponseDetails	Os detalhes da resposta de erro.
GroupDetails	Detalhes específicos do grupo. Aplicável quando o tipo principal é `Group`.
GroupPrincipal	Representa um grupo de segurança.
GroupType	O tipo do grupo. Tipos de grupo adicionais podem ser adicionados ao longo do tempo.
ItemTag	Representa uma tag aplicada em um item.
ItemType	O tipo do item. Tipos de itens adicionais podem ser adicionados ao longo do tempo.
PayloadType	O tipo de carga útil da peça de definição. Ao longo do tempo, podem ser adicionados tipos de carga útil adicionais.
PrincipalType	O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.
SemanticModel	Um objeto de modelo semântico.
SemanticModelCreationPayload	Carga útil de criação para criar um modelo semântico sem definição.
SemanticModelDefinition	Modelo semântico definição pública objeto. Consulte este artigo para mais detalhes sobre a estrutura da definição do modelo semântico.
SemanticModelDefinitionPart	Objeto de parte de definição de modelo semântico.
SensitivityLabel	Representa uma etiqueta de sensibilidade aplicada a um item.
SensitivityLabelApplyStrategy	A estratégia para aplicar o rótulo de sensibilidade. O valor padrão é ApplyOrFail. Tipos adicionais podem ser adicionados ao longo do tempo.
SensitivityLabelSettings	As definições da etiqueta de sensibilidade.
ServicePrincipalDetails	Detalhes específicos da entidade de serviço. Aplicável quando o tipo principal é `ServicePrincipal`.
ServicePrincipalPrincipal	Representa um principal de serviço Microsoft Entra.
ServicePrincipalProfileDetails	Detalhes do perfil da entidade de serviço. Aplicável quando o tipo principal é `ServicePrincipalProfile`.
ServicePrincipalProfilePrincipal	Representa um perfil de principal de serviço.
UserDetails	Detalhes específicos principais do usuário. Aplicável quando o tipo principal é `User`.
UserPrincipal	Representa um principal utilizador Microsoft Entra.

CreateSemanticModelRequest

Object

Crie carga útil de solicitação de modelo semântico.

Nome	Tipo	Descrição
creationPayload	SemanticModelCreationPayload	A carga útil de criação para criar um modelo semântico sem uma definição completa. Forneça URLs de tabelas OneLake para criar um modelo DirectLake, ou omita ambos `definition` e `creationPayload` crie um modelo semântico vazio. Utilizar `definition` ou `creationPayload`. Não é possível usar os dois ao mesmo tempo.
definition	SemanticModelDefinition	A definição pública do modelo semântico. Utilizar `definition` ou `creationPayload`. Não é possível usar os dois ao mesmo tempo.
description	string	A descrição do modelo semântico. O comprimento máximo é de 256 caracteres.
displayName	string	O nome de exibição do modelo semântico. O nome para exibição deve seguir regras de nomenclatura de acordo com o tipo de item.
folderId	string (uuid)	O ID da pasta. Se não especificado ou nulo, o modelo semântico é criado com o espaço de trabalho como sua pasta.
sensitivityLabelSettings	SensitivityLabelSettings	As definições da etiqueta de sensibilidade para o modelo semântico.

EntireTenantPrincipal

Object

Representa um principal inquilino

Nome	Tipo	Descrição
displayName	string	O nome de exibição da entidade de segurança.
id	string (uuid)	O ID da entidade de segurança.
type	string: EntireTenant	O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.

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

O objeto de detalhes do recurso relacionado ao erro.

Nome	Tipo	Descrição
resourceId	string	A ID do recurso envolvida 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	Os detalhes do recurso relacionados ao erro.
requestId	string (uuid)	ID da solicitação associada ao erro.

ErrorResponseDetails

Object

Os detalhes da 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.
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	Os detalhes do recurso relacionados ao erro.

GroupDetails

Object

Detalhes específicos do grupo. Aplicável quando o tipo principal é Group.

Nome	Tipo	Descrição
groupType	GroupType	O tipo do grupo. Tipos de grupo adicionais podem ser adicionados ao longo do tempo.

GroupPrincipal

Object

Representa um grupo de segurança.

Nome	Tipo	Descrição
displayName	string	O nome de exibição da entidade de segurança.
groupDetails	GroupDetails	Detalhes específicos do grupo. Aplicável quando o tipo principal é `Group`.
id	string (uuid)	O ID da entidade de segurança.
type	string: Group	O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.

GroupType

Enumeração

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

Valor	Descrição
Unknown	O tipo de grupo principal é desconhecido.
SecurityGroup	Principal é um grupo de segurança.
DistributionList	Principal é uma lista de distribuição.

ItemTag

Object

Representa uma tag aplicada em um item.

Nome	Tipo	Descrição
displayName	string	O nome da tag.
id	string (uuid)	O ID da tag.

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.
Monitoring	Um item de monitorização.
DeploymentPlan	Um plano de desdobramento.

PayloadType

Enumeração

O tipo de carga útil da peça de definição. Ao longo do tempo, podem ser adicionados tipos de carga útil adicionais.

Valor	Descrição
InlineBase64	Base em linha 64.

PrincipalType

Enumeração

O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.

Valor	Descrição
User	O principal é um utilizador principal da Microsoft Entra.
ServicePrincipal	O principal é um principal do serviço Microsoft Entra.
Group	Principal é um grupo de segurança.
ServicePrincipalProfile	Principal é um perfil de entidade de serviço.
EntireTenant	Principal representa todos os usuários locatários.

SemanticModel

Object

Um objeto de modelo semântico.

Nome	Tipo	Descrição
defaultIdentity	Principal: EntireTenantPrincipal GroupPrincipal ServicePrincipalPrincipal ServicePrincipalProfilePrincipal UserPrincipal	A identidade padrão do item.
description	string	A descrição do item.
displayName	string	O nome de exibição do item.
folderId	string (uuid)	O ID da pasta.
id	string (uuid)	O ID do item.
logicalId	string (uuid)	O identificador lógico do item. As instâncias correspondentes partilham o mesmo ID lógico. O valor é nulo quando nenhum ID lógico foi atribuído.
sensitivityLabel	SensitivityLabel	A etiqueta de sensibilidade do item.
tags	ItemTag[]	Lista de tags aplicadas.
type	ItemType	O tipo de item.
workspaceId	string (uuid)	O ID do espaço de trabalho.

SemanticModelCreationPayload

Object

Carga útil de criação para criar um modelo semântico sem definição.

Nome	Tipo	Descrição
oneLakeTables	string[] (uri)	Uma lista de URLs de tabelas OneLake para ligar o modelo semântico (máximo 100). Cada URL deve seguir um de dois formatos: `https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{dataItemId}/Tables/{tableName}` para uma tabela no esquema predefinido `dbo` , ou `https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{dataItemId}/Tables/{schemaName}/{tableName}` para uma tabela num esquema personalizado explícito. Os URLs podem referenciar diferentes espaços de trabalho e itens de dados, e um único pedido pode misturar URLs de esquema padrão e de esquema personalizado. O sistema infere nomes de tabelas e colunas a partir da fonte OneLake.

SemanticModelDefinition

Object

Modelo semântico definição pública objeto. Consulte este artigo para mais detalhes sobre a estrutura da definição do modelo semântico.

Nome	Tipo	Descrição
format	string	O formato da definição do modelo semântico.
parts	SemanticModelDefinitionPart[]	Uma lista de partes de definição.

SemanticModelDefinitionPart

Object

Objeto de parte de definição de modelo semântico.

Nome	Tipo	Descrição
path	string	O caminho da parte do modelo semântico.
payload	string	A carga útil parcial do modelo semântico.
payloadType	PayloadType	O tipo de carga útil.

SensitivityLabel

Object

Representa uma etiqueta de sensibilidade aplicada a um item.

Nome	Tipo	Descrição
id	string (uuid)	O ID da etiqueta de sensibilidade.

SensitivityLabelApplyStrategy

Enumeração

A estratégia para aplicar o rótulo de sensibilidade. O valor padrão é ApplyOrFail. Tipos adicionais podem ser adicionados ao longo do tempo.

Valor	Descrição
ApplyOrFail	Aplique o rótulo de sensibilidade ou falhe a operação se não puder ser aplicada.
Ignore	Ignore o rótulo de sensibilidade se não puder ser aplicado e prossiga com a operação sem aplicar o rótulo.

SensitivityLabelSettings

Object

As definições da etiqueta de sensibilidade.

Nome	Tipo	Descrição
labelId	string (uuid)	O ID da etiqueta de sensibilidade.
sensitivityLabelApplyStrategy	SensitivityLabelApplyStrategy	A estratégia para aplicar o rótulo de sensibilidade.

ServicePrincipalDetails

Object

Detalhes específicos da entidade de serviço. Aplicável quando o tipo principal é ServicePrincipal.

Nome	Tipo	Descrição
aadAppId	string (uuid)	O Microsoft Entra AppId, do principal do serviço.

ServicePrincipalPrincipal

Object

Representa um principal de serviço Microsoft Entra.

Nome	Tipo	Descrição
displayName	string	O nome de exibição da entidade de segurança.
id	string (uuid)	O ID da entidade de segurança.
servicePrincipalDetails	ServicePrincipalDetails	Detalhes específicos da entidade de serviço. Aplicável quando o tipo principal é `ServicePrincipal`.
type	string: ServicePrincipal	O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.

ServicePrincipalProfileDetails

Object

Detalhes do perfil da entidade de serviço. Aplicável quando o tipo principal é ServicePrincipalProfile.

Nome	Tipo	Descrição
parentPrincipal	Principal: EntireTenantPrincipal GroupPrincipal ServicePrincipalPrincipal ServicePrincipalProfilePrincipal UserPrincipal	A entidade principal do perfil da entidade de serviço.

ServicePrincipalProfilePrincipal

Object

Representa um perfil de principal de serviço.

Nome	Tipo	Descrição
displayName	string	O nome de exibição da entidade de segurança.
id	string (uuid)	O ID da entidade de segurança.
servicePrincipalProfileDetails	ServicePrincipalProfileDetails	Detalhes do perfil da entidade de serviço. Aplicável quando o tipo principal é `ServicePrincipalProfile`.
type	string: ServicePrincipalProfile	O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.

UserDetails

Object

Detalhes específicos principais do usuário. Aplicável quando o tipo principal é User.

Nome	Tipo	Descrição
userPrincipalName	string	O nome principal do usuário.

UserPrincipal

Object

Representa um principal utilizador Microsoft Entra.

Nome	Tipo	Descrição
displayName	string	O nome de exibição da entidade de segurança.
id	string (uuid)	O ID da entidade de segurança.
type	string: User	O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.
userDetails	UserDetails	Detalhes específicos principais do usuário. Aplicável quando o tipo principal é `User`.