Gerencie o ambiente por meio de APIs públicas

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

Importante

Este recurso está em pré-visualização.

Resumo das APIs de ambiente disponíveis

API	Description	Categoria
Criar ambiente	Crie um novo ambiente no espaço de trabalho.	Geral
Obter ambiente	Obtenha os metadados de um ambiente. A resposta inclui o estado do ambiente.	Geral
Ambiente de atualização	Atualize os metadados de um ambiente, como nome e descrição.	Geral
Eliminar ambiente	Exclua um ambiente existente.	Geral
Listar ambiente no espaço de trabalho	Obtenha a lista de ambiente em um espaço de trabalho.	Geral
Ambiente de publicação	Acione a publicação do ambiente com as alterações pendentes atuais.	Geral
Cancelamento de publicação	Cancelar uma publicação contínua do ambiente	Geral
Obter computação do Spark publicada	Obtenha as configurações de computação do Spark que são eficazes.	Computação de faísca
Obter computação do Spark de preparo	Obtenha as configurações completas de computação de preparação. As configurações de preparo incluem as configurações de computação publicadas e pendentes.	Computação de faísca
Obter bibliotecas publicadas	Obtenha a lista de bibliotecas que é eficaz.	Bibliotecas
Obter bibliotecas de preparo	Obtenha a lista completa da biblioteca de preparação. Esta lista inclui as bibliotecas publicadas e pendentes.	Bibliotecas
Carregar bibliotecas de preparo	Adicionar uma biblioteca personalizada ou uma/várias bibliotecas públicas no ambiente.	Bibliotecas
Excluir bibliotecas de preparo	Exclua uma biblioteca personalizada de preparo ou toda a biblioteca pública.	Bibliotecas

Saiba mais sobre as APIs públicas de ambiente em APIs de item - Ambiente

Casos de uso da API pública do ambiente

Esta seção orienta você por vários cenários comuns ao lidar com o ambiente. Você pode substituir o {WORKSPACE_ID} e {ARTIFACT_ID} nos exemplos a seguir por valores apropriados.

Criar um novo ambiente

Você pode criar um novo ambiente vazio usando a seguinte API.

• Pedido de amostra

  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 preparo de upload/exclusão para gerenciar a seção de biblioteca no ambiente

Verifique o ambiente nas bibliotecas publicadas

Antes de adicionar/excluir bibliotecas, você pode usar a API obter bibliotecas publicadas para verificar quais bibliotecas são eficazes no momento.

• Pedido de amostra

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

• Resposta da amostra

  {
      "customLibraries": {
          "wheelFiles": [
              "samplewheel-0.18.0-py2.py3-none-any.whl"
          ],
          "pyFiles": [
              "samplepython.py"
          ],
          "jarFiles": [
              "samplejar.jar"
          ],
          "rTarFiles": [
              "sampleR.tar.gz"
          ]
      },
      "environmentYml": "dependencies:\r\n- pip:\r\n  - matplotlib==3.4.3"
  }
  

Carregar as bibliotecas

A API para carregar a biblioteca de preparo aceita um arquivo de cada vez. Os tipos de ficheiro suportados são .whl, .jar, .tar.gz, .py e environment.yml para biblioteca pública. Você pode especificar o arquivo por meio do tipo de conteúdo multipart/form-data.

Nota

• Para manipular a biblioteca pública de forma mais eficiente, é altamente recomendável compor todas as bibliotecas esperadas do PyPI e conda em um arquivo environment.yml.
• A API de upload permite até 200 MB de arquivo em uma solicitação, biblioteca que excede esse limite de tamanho atualmente não é suportada na API pública.

• Pedidos de amostra

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

Excluindo as bibliotecas

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

Nota

• Se você especificar environment.yml como o arquivo a ser excluído, estará removendo todas as bibliotecas públicas.
• Se você quiser remover um subconjunto de biblioteca pública existente, use a biblioteca de upload em vez disso e carregue um environment.yml que contenha apenas as bibliotecas esperadas. O environment.yml carregado substitui totalmente a secção da biblioteca pública existente.

• Pedidos de amostra

  DELETE https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries?libraryToDelete=fuzzywuzzy-0.18.0-py2.py3-none-any.whl
  

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 o cálculo do Spark publicado para o ambiente

Antes de alterar as configurações do ambiente, você pode usar a API de computação do Spark publicada para verificar quais configurações de computação do Spark são efetivas no momento.

• Pedido de amostra

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

• Resposta da amostra

  {
      "instancePool": {
          "name": "Starter Pool",
          "type": "Workspace"
      },
      "driverCores": 4,
      "driverMemory": "56g",
      "executorCores": 4,
      "executorMemory": "56g",
      "dynamicExecutorAllocation": {
          "enabled": false,
          "minExecutors": 1,
          "maxExecutors": 1
      },
      "sparkProperties": {
          "spark.acls.enable": "false"
      },
      "runtimeVersion": "1.2"
  }
  

Atualizar as configurações de computação

Você pode atualizar o tempo de execução do Spark, alternar para outro pool, refinar a configuração de computação e adicionar/remover propriedades do Spark editando o corpo da solicitação desta API.

Você pode alternar o pool anexado especificando o nome e o pool do pool. Especifique o nome do pool para Starter Pool alternar o pool para as configurações padrão. Para obter a lista completa dos pools personalizados disponíveis do espaço de trabalho pela API REST, consulte Pools personalizados - List Workspace Custom Pools

Se desejar remover uma propriedade Spark existente, você precisará especificar o valor como null com a chave que deseja remover, conforme mostrado no exemplo a seguir.

• Pedido de amostra

  PATCH https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/sparkcompute
  
  {
      "instancePool": {
          "name": "Starter Pool",
          "type": "Workspace"
      },
      "driverCores": 4,
      "driverMemory": "56g",
      "executorCores": 4,
      "executorMemory": "56g",
      "dynamicExecutorAllocation": {
          "enabled": false,
          "minExecutors": 1,
          "maxExecutors": 1
      },
      "sparkProperties": {
          "spark.acls.enable": null
      },
      "runtimeVersion": "1.2"
  }
  

Tornar as alterações efetivas

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

Preparar-se para uma publicação

O ambiente pode aceitar uma publicação de cada vez. Antes de publicar seu ambiente, você pode validar o status do ambiente e ter uma revisão final das alterações de preparação. Depois que o ambiente é publicado com êxito, todas as configurações no estado de preparo entram em vigor.

• Etapa 1: obter 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. Certifique-se de que não há nenhuma publicação em andamento antes de passar para a próxima etapa.

• Etapa 2: obter as bibliotecas de preparação/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
  
  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/sparkcompute
  

Acionar a publicação do ambiente

As alterações feitas nas bibliotecas de preparo e na computação do Spark são armazenadas em cache, mas exigem publicação para entrar em vigor. Siga o exemplo a seguir para acionar a publicação.

• Pedido de amostra

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

• Resposta da amostra

  {
      "publishDetails":
      {
          "state": "Running",
          "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
          "startTime": "2024-03-29T14:17:09.0697022Z",
          "componentPublishInfo": {
              "sparkLibraries": {
                  "state": "Running"
              },
              "sparkSettings": {
                  "state": "Running"
              }
          }
      }
  }   
  

Durante a publicação, você também pode ligar para a API seguinte para cancelá-la .

• Pedido de amostra

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

Conteúdos relacionados

• Crie, configure e use um ambiente no Microsoft Fabric.
• APIs de item - Ambiente.