Items - Create Semantic Model

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

Cria um modelo semântico no workspace especificado.
Essa API dá suporte a LRO (operações de execução longa).

A API dá suporte a três modos de criação: (1) fornece um definition controle total sobre a estrutura do modelo, (2) fornece urls creationPayload de tabela do OneLake para criar um modelo DirectLake ou (3) omite ambos para criar um modelo semântico vazio. Use definition ou creationPayload. Você não pode usar ambos ao mesmo tempo.

Permissões

O chamador deve ter uma função de workspace de colaborador . Ao criar um modelo DirectLake com um creationPayload que faça referência a tabelas OneLake, o chamador também deve ter acesso a cada item de dados ou lakehouse de origem referenciado, inclusive quando essas fontes residem em um workspace diferente (fontes entre workspaces).

Escopos delegados necessários

SemanticModel.ReadWrite.All ou Item.ReadWrite.All

Limitações

Microsoft Entra identidades com suporte

Essa API dá suporte aos Microsoft identities listados nesta seção.

Identidade Apoio
Utilizador Sim
Entidade de serviço e identidades gerenciadas Sim

Interfase

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

Parâmetros de URI

Nome Em Obrigatório Tipo Description
workspaceId
 path True

string (uuid)

A ID do workspace.

Corpo da solicitação

Nome Obrigatório Tipo Description
displayName True

string

O nome de exibição do modelo semântico. O nome de exibição deve seguir regras de nomenclatura de acordo com o tipo de item.
creationPayload

SemanticModelCreationPayload

O conteúdo de criação para criar um modelo semântico sem uma definição completa. Forneça URLs de tabela do OneLake para criar um modelo DirectLake ou omita ambos definition e creationPayload crie um modelo semântico vazio. Use definition ou creationPayload. Você não pode usar ambos ao mesmo tempo.
definition

SemanticModelDefinition

A definição pública do modelo semântico. Use definition ou creationPayload. Você não pode usar ambos ao mesmo tempo.
description

string

A descrição do modelo semântico. O comprimento máximo é de 256 caracteres.
folderId

string (uuid)

A ID da pasta. Se não for especificado ou nulo, o modelo semântico será criado com o workspace como sua pasta.
sensitivityLabelSettings

SensitivityLabelSettings

As configurações de rótulo de confidencialidade para o modelo semântico.

Respostas

Nome Tipo Description
201 Created

SemanticModel

Criado com êxito
202 Accepted

Provisionamento de modelo semântico aceito por solicitação em andamento.

Cabeçalhos

  • Location: string
  • x-ms-operation-id: string
  • Retry-After: integer
429 Too Many Requests

ErrorResponse

O limite de taxa de serviço foi excedido. O servidor retorna um Retry-After cabeçalho indicando, em segundos, quanto tempo o cliente deve aguardar antes de enviar solicitações adicionais.

Cabeçalhos

Retry-After: integer
Other Status Codes

ErrorResponse

Códigos de erro comuns:

  • ItemDisplayNameAlreadyInUse – O nome de exibição do item já está sendo usado.

  • CorruptedPayload – O conteúdo fornecido está corrompido.

  • MutuallyExclusiveProperties - O definition e creationPayload não pode ser fornecido.

  • InvalidOneLakeTableUrl – Uma ou mais URLs de tabela do OneLake são inválidas.

  • DuplicateTableName – Nomes de tabela duplicados 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

Solicitação de exemplo

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 de exemplo

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

Solicitação de exemplo

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 de exemplo

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

Solicitação de exemplo

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

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

Resposta de exemplo

Código de status:
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 status:
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 Description
CreateSemanticModelRequest

Criar conteúdo de solicitação de modelo semântico.
EntireTenantPrincipal

Representa uma entidade de segurança de locatário
ErrorParameter

Um parâmetro estruturado que fornece contexto legível por computador adicional 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 marca aplicada em um item.
ItemType

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

O tipo da carga da parte de definição. Tipos de conteúdo adicionais podem ser adicionados ao longo do tempo.
PrincipalType

O tipo da entidade de segurança. Tipos de entidades de segurança adicionais podem ser adicionados ao longo do tempo.
SemanticModel

Um objeto de modelo semântico.
SemanticModelCreationPayload

Conteúdo de criação para criar um modelo semântico sem uma definição.
SemanticModelDefinition

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

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

Representa um rótulo de confidencialidade aplicado a um item.
SensitivityLabelApplyStrategy

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

As configurações do rótulo de confidencialidade.
ServicePrincipalDetails

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

Representa uma entidade 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 entidade de serviço.
UserDetails

Detalhes específicos da entidade de usuário. Aplicável quando o tipo principal é User.
UserPrincipal

Representa uma entidade de Microsoft Entra usuário.

CreateSemanticModelRequest

Objeto

Criar conteúdo de solicitação de modelo semântico.

Nome Tipo Description
creationPayload

SemanticModelCreationPayload

O conteúdo de criação para criar um modelo semântico sem uma definição completa. Forneça URLs de tabela do OneLake para criar um modelo DirectLake ou omita ambos definition e creationPayload crie um modelo semântico vazio. Use definition ou creationPayload. Você não pode usar ambos ao mesmo tempo.
definition

SemanticModelDefinition

A definição pública do modelo semântico. Use definition ou creationPayload. Você não pode usar ambos 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 de exibição deve seguir regras de nomenclatura de acordo com o tipo de item.
folderId

string (uuid)

A ID da pasta. Se não for especificado ou nulo, o modelo semântico será criado com o workspace como sua pasta.
sensitivityLabelSettings

SensitivityLabelSettings

As configurações de rótulo de confidencialidade para o modelo semântico.

EntireTenantPrincipal

Objeto

Representa uma entidade de segurança de locatário

Nome Tipo Description
displayName

string

O nome de exibição da entidade de segurança.
id

string (uuid)

A ID da entidade de segurança.
type string:

EntireTenant

O tipo da entidade de segurança. Tipos de entidades de segurança adicionais podem ser adicionados ao longo do tempo.

ErrorParameter

Objeto

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

Nome Tipo Description
message

string

Uma descrição legível pelo ser humano do significado do parâmetro.
name

string

O identificador de parâmetro.
value

string

O valor do parâmetro.

ErrorRelatedResource

Objeto

O objeto de detalhes do recurso relacionado ao erro.

Nome Tipo Description
resourceId

string

A ID do recurso envolvida no erro.
resourceType

string

O tipo do recurso envolvido no erro.

ErrorResponse

Objeto

A resposta de erro.

Nome Tipo Description
errorCode

string

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

boolean

Quando true, a solicitação pode ser repetida. Use o Retry-After cabeçalho de resposta para determinar o atraso, se disponível.
message

string

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

ErrorResponseDetails[]

Lista de detalhes de erro adicionais.
parameters

ErrorParameter[]

Parâmetros estruturados que fornecem contexto legível por computador adicional sobre o erro.
relatedResource

ErrorRelatedResource

Os detalhes do recurso relacionado ao erro.
requestId

string (uuid)

ID da solicitação associada ao erro.

ErrorResponseDetails

Objeto

Os detalhes da resposta de erro.

Nome Tipo Description
errorCode

string

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

string

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

ErrorParameter[]

Parâmetros estruturados que fornecem contexto legível por computador adicional sobre o erro.
relatedResource

ErrorRelatedResource

Os detalhes do recurso relacionado ao erro.

GroupDetails

Objeto

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

Nome Tipo Description
groupType

GroupType

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

GroupPrincipal

Objeto

Representa um grupo de segurança.

Nome Tipo Description
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)

A ID da entidade de segurança.
type string:

Group

O tipo da entidade de segurança. Tipos de entidades de segurança adicionais podem ser adicionados ao longo do tempo.

GroupType

Enumeração

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

Valor Description
Unknown

O tipo de grupo principal é desconhecido.
SecurityGroup

A entidade de segurança é um grupo de segurança.
DistributionList

Principal é uma lista de distribuição.

ItemTag

Objeto

Representa uma marca aplicada em um item.

Nome Tipo Description
displayName

string

O nome da marca.
id

string (uuid)

A ID da marca.

ItemType

Enumeração

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

Valor Description
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 bloco de anotações.
SparkJobDefinition

Uma definição de trabalho do Spark.
MLExperiment

Um experimento de aprendizado de máquina.
MLModel

Um modelo de machine learning.
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

Um item de API para GraphQL.
MountedDataFactory

Um MountedDataFactory.
SQLDatabase

Um SQLDatabase.
CopyJob

Um trabalho de cópia.
VariableLibrary

Um VariableLibrary.
Dataflow

Um fluxo de dados.
ApacheAirflowJob

Um ApacheAirflowJob.
WarehouseSnapshot

Um instantâneo do Warehouse.
DigitalTwinBuilder

Um DigitalTwinBuilder.
DigitalTwinBuilderFlow

Um fluxo do Construtor de Gêmeos Digitais.
MirroredAzureDatabricksCatalog

Um catálogo espelhado do Azure Databricks.
Map

Um mapa.
AnomalyDetector

Um Detector de Anomalias.
UserDataFunction

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

Um GraphModel.
GraphQuerySet

Um Graph QuerySet.
SnowflakeDatabase

Um Banco de Dados Snowflake para armazenar tabelas iceberg criadas a partir da conta snowflake.
OperationsAgent

Um OperationsAgent.
CosmosDBDatabase

Um banco de dados do Cosmos DB.
Ontology

Uma ontologia.
EventSchemaSet

Um EventSchemaSet.
DataAgent

Um DataAgent.
MirroredCatalog

Um MirroredCatalog.
PolicySet

Um PolicySet.
AppBackend

Um AppBackend.
OrgApp

Um aplicativo de organização.
OrgAppAudience

Uma audiência de aplicativo da organização.
DataBuildToolJob

Um DataBuildToolJob.
AzureDatabricksStorage

Um item de armazenamento com backup do OneLake para Azure Databricks.
Plan

Um plano.
Monitoring

Um item de monitoramento.
DeploymentPlan

Um plano de implantação.

PayloadType

Enumeração

O tipo da carga da parte de definição. Tipos de conteúdo adicionais podem ser adicionados ao longo do tempo.

Valor Description
InlineBase64

Base 64 embutida.

PrincipalType

Enumeração

O tipo da entidade de segurança. Tipos de entidades de segurança adicionais podem ser adicionados ao longo do tempo.

Valor Description
User

A entidade de segurança é uma entidade de Microsoft Entra usuário.
ServicePrincipal

A entidade de segurança é uma entidade de serviço Microsoft Entra.
Group

A entidade de segurança é um grupo de segurança.
ServicePrincipalProfile

Principal é um perfil de entidade de serviço.
EntireTenant

A entidade de segurança representa todos os usuários do locatário.

SemanticModel

Objeto

Um objeto de modelo semântico.

Nome Tipo Description
defaultIdentity Principal:

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)

A ID da pasta.
id

string (uuid)

A ID do item.
logicalId

string (uuid)

O identificador lógico do item. As instâncias de item correspondentes compartilham a mesma ID lógica. O valor é nulo quando nenhuma ID lógica foi atribuída.
sensitivityLabel

SensitivityLabel

O rótulo de confidencialidade do item.
tags

ItemTag[]

Lista de marcas aplicadas.
type

ItemType

O tipo de item.
workspaceId

string (uuid)

A ID do workspace.

SemanticModelCreationPayload

Objeto

Conteúdo de criação para criar um modelo semântico sem uma definição.

Nome Tipo Description
oneLakeTables

string[] (uri)

Uma lista de URLs de tabela do OneLake para conectar o modelo semântico (no máximo 100). Cada URL deve seguir um dos dois formatos: https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{dataItemId}/Tables/{tableName} para uma tabela no esquema padrão dbo ou https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{dataItemId}/Tables/{schemaName}/{tableName} para uma tabela em um esquema personalizado explícito. As URLs podem fazer referência a diferentes workspaces e itens de dados, e uma única solicitação pode misturar URLs de esquema padrão e de esquema personalizado. O sistema infere nomes de tabela e colunas da origem do OneLake.

SemanticModelDefinition

Objeto

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

Nome Tipo Description
format

string

O formato da definição de modelo semântico.
parts

SemanticModelDefinitionPart[]

Uma lista de partes de definição.

SemanticModelDefinitionPart

Objeto

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

Nome Tipo Description
path

string

O caminho da parte do modelo semântico.
payload

string

O conteúdo da parte semântica do modelo.
payloadType

PayloadType

O tipo de conteúdo.

SensitivityLabel

Objeto

Representa um rótulo de confidencialidade aplicado a um item.

Nome Tipo Description
id

string (uuid)

A ID do rótulo de confidencialidade.

SensitivityLabelApplyStrategy

Enumeração

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

Valor Description
ApplyOrFail

Aplique o rótulo de confidencialidade ou falhe na operação se ela não puder ser aplicada.
Ignore

Ignore o rótulo de confidencialidade se ele não puder ser aplicado e prossiga com a operação sem aplicar o rótulo.

SensitivityLabelSettings

Objeto

As configurações do rótulo de confidencialidade.

Nome Tipo Description
labelId

string (uuid)

A ID do rótulo de confidencialidade.
sensitivityLabelApplyStrategy

SensitivityLabelApplyStrategy

A estratégia para aplicar o rótulo de confidencialidade.

ServicePrincipalDetails

Objeto

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

Nome Tipo Description
aadAppId

string (uuid)

AppId Microsoft Entra da entidade de serviço.

ServicePrincipalPrincipal

Objeto

Representa uma entidade de serviço Microsoft Entra.

Nome Tipo Description
displayName

string

O nome de exibição da entidade de segurança.
id

string (uuid)

A 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 da entidade de segurança. Tipos de entidades de segurança adicionais podem ser adicionados ao longo do tempo.

ServicePrincipalProfileDetails

Objeto

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

Nome Tipo Description
parentPrincipal Principal:

A entidade pai do perfil da entidade de serviço.

ServicePrincipalProfilePrincipal

Objeto

Representa um perfil de entidade de serviço.

Nome Tipo Description
displayName

string

O nome de exibição da entidade de segurança.
id

string (uuid)

A 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 da entidade de segurança. Tipos de entidades de segurança adicionais podem ser adicionados ao longo do tempo.

UserDetails

Objeto

Detalhes específicos da entidade de usuário. Aplicável quando o tipo principal é User.

Nome Tipo Description
userPrincipalName

string

Nome principal do usuário.

UserPrincipal

Objeto

Representa uma entidade de Microsoft Entra usuário.

Nome Tipo Description
displayName

string

O nome de exibição da entidade de segurança.
id

string (uuid)

A ID da entidade de segurança.
type string:

User

O tipo da entidade de segurança. Tipos de entidades de segurança adicionais podem ser adicionados ao longo do tempo.
userDetails

UserDetails

Detalhes específicos da entidade de usuário. Aplicável quando o tipo principal é User.