Gerenciar o ambiente por meio de APIs públicas

A API REST do Microsoft Fabric fornece um ponto de extremidade de serviço para operações de criação, leitura, atualização e exclusão (CRUD) de um item do Fabric. Este artigo descreve as APIs REST de ambiente disponíveis e o uso delas.

Migrar as APIs de ambiente para sua versão de GA estável

Importante

A versão GA inclui atualizações no contrato de solicitação/resposta de APIs existentes, descontinuações de API e novas APIs. Você pode encontrar os detalhes nas seções a seguir.
Um novo parâmetro beta de consulta é introduzido para facilitar a transição de alterações de contrato de solicitação/resposta. O parâmetro de consulta beta é padrão para True, até 31 de março de 2026, tornando os contratos de visualização ainda disponíveis. Defina o valor para False para começar a usar a versão estável dos contratos.
Preview o parâmetro de consulta foi substituído por beta. Para compatibilidade com versões anteriores, a versão prévia ainda tem suporte e se comporta da mesma forma que beta.
As APIs que serão descontinuadas continuarão a ter suporte até 31 de março de 2026. Por favor, use as APIs recém-introduzidas para substituí-las o mais rápido possível.

APIs com atualização de contrato de solicitação/resposta

Categoria	API	Descrição	Anotações	Visualizar a versão de prévia do Swagger	Versão de lançamento do Swagger
Operação do item	Publicar ambiente	Dispare a operação de publicação do ambiente com as alterações pendentes atuais.	Atualização no contrato de serviço de resposta.	Ambiente de publicação (versão prévia)	Ambiente de publicação
De preparo	Listar bibliotecas de preparo	Obtenha a lista completa de bibliotecas de preparo. Esta lista inclui as bibliotecas publicadas e pendentes.	Atualização no contrato de serviço de resposta.	Listar bibliotecas de testes (Prévia)	Listar bibliotecas de pré-produção
De preparo	Listar a computação do Spark em estágio preparatório	Obtenha as configurações completas de computação de preparo. As configurações de preparo incluem as configurações de computação publicadas e pendentes.	Atualização no contrato de serviço de resposta.	Listar computação Spark do ambiente de ensaio (prévia)	Listar computação de Spark em estágio
De preparo	Atualizar a computação do Spark	Atualize as configurações de computação e as propriedades do Spark para um ambiente.	Atualização nos contratos de solicitação e resposta.	Atualizar a computação do Spark (versão prévia)	Atualizar a computação do Spark
Publicado	Listar bibliotecas publicadas	Obtenha as bibliotecas que são publicadas e eficazes para uso em sessões do Spark.	Atualização no contrato de serviço de resposta.	Listar bibliotecas publicadas (versão prévia)	Listar bibliotecas publicadas
Publicado	Listar os recursos computacionais publicados do Spark	Obtenha as configurações de computação do Spark e as propriedades do Spark que são publicadas e eficazes nas sessões do Spark.	Atualização no contrato de serviço de resposta.	Listar bibliotecas publicadas (versão prévia)	Listar bibliotecas publicadas

O beta parâmetro usa como padrão True até 31 de março de 2026, ou seja, o sistema considera o parâmetro como True se a solicitação estivesse enviando sem especificar esse parâmetro até a data de substituição. É altamente recomendável migrar suas implementações para a versão estável definindo explicitamente o parâmetro beta para False o mais rápido possível.

Usando a API List staging libraries como exemplo, que possui uma atualização na resposta da API.

Ao enviar a solicitação com beta parâmetro como True

Solicitação de exemplo:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries?beta=True

Resposta de exemplo:

{
  "customLibraries": {
    "wheelFiles": [
      "samplewheel-0.18.0-py2.py3-none-any.whl"
    ],
    "pyFiles": [
      "samplepython.py"
    ],
    "jarFiles": [
      "samplejar.jar"
    ],
    "rTarFiles": [
      "sampleR.tar.gz"
    ]
  },
  "environmentYml": "name: sample-environment\ndependencies:\n  - fuzzywuzzy==0.0.1\n  - matplotlib==0.0.1"
}

Ao enviar a solicitação com preview parâmetro como False

Solicitação de exemplo:

  GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries?beta=False

Resposta de exemplo:

{
  "libraries": [
    {
      "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
      "libraryType": "Custom"
    },
    {
      "name": "fuzzywuzzy",
      "libraryType": "External",
      "version": "0.0.1"
    }
  ],
  "continuationToken": "null",
  "continuationUri": "null"
}

APIs a serem descontinuadas em breve

Importante

As APIs a serem preteridas continuarão a ter suporte até 31 de março de 2026. É altamente recomendável usar APIs recém-introduzidas para substituir suas implementações o mais rápido possível.

Categoria	API	Descrição	Observação
De preparo	Carregar bibliotecas de preparo	Adicione uma biblioteca personalizada ou uma/várias bibliotecas públicas no ambiente.	Suporte até 31 de março de 2026, use as APIs recém-introduzidas `Import external libraries`/`Upload custom library` para substituí-las.
De preparo	Excluir bibliotecas de teste	Exclua uma biblioteca personalizada de estágio ou todas as bibliotecas públicas.	Suporte até 31 de março de 2026, use as APIs recém-introduzidas `Remove external library`/`Delete custom library` para substituí-las.

Abaixo estão alguns exemplos que abrangem os cenários para gerenciar bibliotecas temporárias.

Adicionar as bibliotecas públicas em seu ambiente

Anteriormente, você pode usar Upload staging libraries a API para carregar o arquivo YAML atualizado e agora pode usar Import external libraries a API para importar o YAML atualizado.
Remover uma biblioteca pública no seu ambiente

Anteriormente, você pode usar Upload staging libraries a API para carregar o arquivo YAML atualizado e agora pode usar Remove external library a API para removê-lo.
Excluir todas as bibliotecas públicas do seu ambiente

Anteriormente, você pode usar Delete staging libraries a API para excluir todas as bibliotecas públicas e agora pode usar Remove external library a API para remover as bibliotecas públicas uma a uma ou usar Import external libraries para carregar um arquivo YAML vazio para obter as mesmas funcionalidades.

Novas APIs

Categoria	API	Descrição	Observação
Operação do item	Criar ambiente com definição	Crie um novo ambiente com definição.	Nova API.
Operação do item	Obter definição de ambiente	Obtenha a definição de um ambiente.	Nova API.
Operação do item	Atualizar definição de ambiente	Atualize a definição de um ambiente.	Nova API.
De preparo	Importar bibliotecas externas	Carregue bibliotecas externas como um arquivo environment.yml no ambiente. Ele substitui a lista de bibliotecas externas existentes em um ambiente.	Nova API.
De preparo	Exportar bibliotecas externas	Obtenha as bibliotecas externas completas como um arquivo environment.yml .	Nova API.
De preparo	Remover biblioteca externa	Exclua uma biblioteca externa de um ambiente. Essa API aceita uma biblioteca por vez.	Nova API.
De preparo	Carregar biblioteca personalizada	Carregue um pacote personalizado no ambiente. Essa API permite um upload de arquivo por vez. Os formatos de arquivo com suporte são .jar, .py, .whl e .tar.gz.	Nova API.
De preparo	Excluir biblioteca personalizada	Exclua um pacote personalizado do ambiente. Coloque o nome completo do pacote personalizado com a extensão na solicitação de API para que ele seja removido.	Nova API.
Publicado	Exportar bibliotecas externas	Obtenha as bibliotecas externas publicadas como um arquivo environment.yml .	Nova API.

APIs sem atualização

Categoria	API	Descrição
Operação do item	Criar ambiente	Crie um novo ambiente vazio no espaço de trabalho.
Operação do item	Obter ambiente	Obtenha os metadados de um ambiente. A resposta inclui o status do ambiente.
Operação do item	Excluir ambiente	Excluir um ambiente existente.
Operação do item	Ambiente de lista	Obtenha uma lista de ambientes em um espaço de trabalho.
Operação do item	Atualizar o ambiente	Atualize os metadados de um ambiente, como nome e descrição.
Operação do item	Cancelar ambiente de publicação	Cancele a operação de publicação em andamento no ambiente.

Para saber mais sobre as APIs públicas de ambiente, consulte APIs de Item – Ambiente.

Casos de uso de API pública do ambiente

Importante

Esta seção é demonstrada com a versão de lançamento estável das APIs.

Esta seção demonstra como usar as APIs para obter cenários específicos ao gerenciar o Ambiente. Você pode substituir as propriedades {WORKSPACE_ID} e {ARTIFACT_ID} nos exemplos a seguir por valores apropriados.

Criar um novo ambiente

Para criar um ambiente vazio, use a API a seguir.

Solicitação de exemplo

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments

{
    "displayName": "Environment_1",
    "description": "An environment description"
}

Gerenciar bibliotecas de preparo

Você pode usar as APIs de bibliotecas de staging para upload e exclusão para gerenciar a seção de biblioteca no ambiente.

Verifique as bibliotecas publicadas para o ambiente

Antes de adicionar ou excluir uma biblioteca, use a API Obter Bibliotecas Publicadas para verificar quais bibliotecas estão em vigor no momento.

Solicitação de exemplo

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/libraries?beta=False

Resposta de exemplo

{
  "libraries": [
    {
      "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
      "libraryType": "Custom"
    },
    {
      "name": "fuzzywuzzy",
      "libraryType": "External",
      "version": "0.0.1"
    }
  ],
  "continuationToken": "null",
  "continuationUri": "null"
}

Importar bibliotecas públicas ou carregar biblioteca personalizada

Você pode usar a Importação de bibliotecas externas e carregar APIs de biblioteca personalizada para adicionar novas bibliotecas públicas/personalizadas ao seu ambiente. A API de importação de bibliotecas externas aceita environment.yml arquivo enquanto os tipos de arquivo com suporte são .whl, .jar, .tar.gz.py para carregar a API de biblioteca personalizada.

Observação

Para manipular a biblioteca pública com mais eficiência, recomendamos que você componha todas as bibliotecas esperadas do PyPI e do Conda em um arquivo environment.yml .

A API de carregamento permite até um arquivo de 200 MB em uma solicitação. Não há suporte para uma biblioteca que exceda esse limite de tamanho atualmente em APIs públicas.

Solicitações de exemplo

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/importExternalLibraries

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/samplelibrary.jar

Excluir a biblioteca personalizada

Ao especificar o nome completo do arquivo de biblioteca com o sufixo de tipo, você pode excluir uma biblioteca personalizada de cada vez.

Observação

Se você quiser remover um subconjunto das bibliotecas públicas existentes ou todas elas, importe um arquivo YAML atualizado por meio Import public libraries da API.

Solicitações de exemplo

DELETE https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/samplelibrary.jar

Gerenciar computação do Spark de preparo

Você pode usar a computação do Spark de preparo de atualização para gerenciar a computação do Spark.

Verifique a computação do Spark publicada para o ambiente

Antes de alterar as configurações do ambiente, use a API de Computação Get Published Spark para verificar quais configurações de computação do Spark estão em vigor no momento.

Solicitação de exemplo

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/sparkcompute?beta=False

Resposta de exemplo

{
  "instancePool": {
    "name": "MyWorkspacePool",
    "type": "Workspace",
    "id": "78942136-106c-4f3e-80fc-7ff4eae11603"
  },
  "driverCores": 4,
  "driverMemory": "56g",
  "executorCores": 4,
  "executorMemory": "56g",
  "dynamicExecutorAllocation": {
    "enabled": false,
    "minExecutors": 1,
    "maxExecutors": 1
  },
  "sparkProperties": [
    {
      "key": "spark.acls.enable",
      "value": "false"
    }
  ],
  "runtimeVersion": "1.2"
}

Atualizar as configurações de computação

Você pode atualizar o runtime do Spark, alternar para outro pool, refinar a configuração de computação e adicionar ou remover propriedades do Spark por meio da edição do corpo da solicitação dessa API.

Você pode alternar o pool anexado especificando o nome do pool e o pool. Especifique o nome do pool como Starter Pool para alternar o pool para as configurações padrão. Para obter a lista completa dos pools personalizados disponíveis do workspace pela API REST, consulte Pools Personalizados – Listar Pools Personalizados do Workspace.

Se você quiser remover uma propriedade spark existente, especifique o valor como null com a chave que deseja remover.

Solicitação de exemplo

PATCH https://api.fabric.microsoft.com/v1/workspaces/f089354e-8366-4e18-aea3-4cb4a3a50b48/environments/707cfd07-cbf1-41da-aad7-dd157ddb8c11/staging/sparkcompute?beta=False

{
  "instancePool": {
    "name": "MyWorkspacePool",
    "type": "Workspace"
  },
  "driverCores": 4,
  "driverMemory": "56g",
  "executorCores": 4,
  "executorMemory": "56g",
  "dynamicExecutorAllocation": {
    "enabled": false,
    "minExecutors": 1,
    "maxExecutors": 1
  },
  "sparkProperties": [
    {
      "key": "spark.acls.enable",
      "value": "false"
    },
    {
      "key": "spark.admin.acls",
      "value": null
    }
  ],
  "runtimeVersion": "1.2"
}

Tornar as alterações efetivas

Use os seguintes conjuntos de APIs para publicar as alterações.

Preparar para uma operação de publicação

O ambiente pode aceitar uma operação de publicação por vez. Antes de publicar seu ambiente, valide o status do ambiente e faça uma revisão final das alterações intermediárias. Depois que o ambiente é publicado com êxito, todas as configurações no estado de preparo se tornam eficazes.

Etapa 1: Obtenha os metadados do ambiente.
```
GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/
```
No corpo da resposta, você pode dizer claramente o estado do ambiente. Verifique se nenhuma operação de publicação está em andamento antes de passar para a próxima etapa.

Etapa 2: Obtenha as bibliotecas intermediárias/capacidades de computação do Spark para ter uma revisão final.

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries?beta=False

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/sparkcompute?beta=False

Disparar a operação de publicação do ambiente

As alterações feitas para as bibliotecas de estágio e a computação do Spark são armazenadas em cache, mas requerem publicação para se tornarem efetivas. Use o próximo exemplo para disparar a operação de publicação. A resposta segue o padrão LRO (operações de execução prolongada) e o código de resposta HTTP 202 pode ser retornado.

Solicitação de exemplo

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/publish?beta=False

Resposta de exemplo

Location: https://api.fabric.microsoft.com/v1/operations/abcdef00-9d7e-469a-abf1-fca847a0ea69
x-ms-operation-id: abcdef00-9d7e-469a-abf1-fca847a0ea69
Retry-After: 120

Durante a operação de publicação, você também pode chamar a API a seguir para cancelá-la.

Solicitação de exemplo

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/cancelPublish

Comentários

Esta página foi útil?

Last updated on 2025-10-09

Compartilhar via

Gerenciar o ambiente por meio de APIs públicas

Migrar as APIs de ambiente para sua versão de GA estável

APIs com atualização de contrato de solicitação/resposta

APIs a serem descontinuadas em breve

Novas APIs

APIs sem atualização

Casos de uso de API pública do ambiente

Criar um novo ambiente

Gerenciar bibliotecas de preparo

Verifique as bibliotecas publicadas para o ambiente

Importar bibliotecas públicas ou carregar biblioteca personalizada

Excluir a biblioteca personalizada

Gerenciar computação do Spark de preparo

Verifique a computação do Spark publicada para o ambiente

Atualizar as configurações de computação

Tornar as alterações efetivas

Preparar para uma operação de publicação

Disparar a operação de publicação do ambiente

Conteúdo relacionado

Comentários

Recursos adicionais