Compartilhar via

Gerenciar o ambiente por meio de APIs públicas

  • Artigo

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.

Importante

Esse recurso está na versão prévia.

Resumo das APIs de ambiente disponíveis

API Descrição 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 status do ambiente. Geral
Atualizar ambiente Atualize os metadados de um ambiente, como nome e descrição. Geral
Excluir ambiente Excluir um ambiente existente. Geral
Listar ambiente no espaço de trabalho Obter a lista de ambientes em um espaço de trabalho. Geral
Publicar ambiente Acione a publicação do ambiente com as alterações pendentes atuais. Geral
Publicar cancelamento Cancelar uma publicação contínua do ambiente Geral
Publicar computação do Spark Obtenha as configurações de computação do Spark que são eficazes. Computação do Spark
Obter computação do Spark de preparo 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. Computação do Spark
Obter bibliotecas publicadas Obtenha a lista de bibliotecas que é eficaz. Bibliotecas
Obter bibliotecas de preparo Obtenha a lista completa de bibliotecas de preparo. 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 do ambiente em APIs de item - Ambiente

Casos de uso de API pública do ambiente

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

Criar um novo ambiente

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

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

Verifique as bibliotecas publicadas para o ambiente

Antes de adicionar/excluir biblioteca, você pode usar a API get published libraries para verificar quais bibliotecas são efetivas no momento.

  • Solicitação de exemplo

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

  • 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": "dependencies:\r\n- pip:\r\n  - matplotlib==3.4.3"
}

Carregando as bibliotecas

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

Observação

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

  • Solicitações de exemplo

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

Excluindo as bibliotecas

Especificando o nome completo do arquivo de biblioteca com o sufixo de tipo, você pode excluir uma biblioteca por vez.

Observação

  • Se você especificar environment.yml como o arquivo a ser excluído, removerá todas as bibliotecas públicas.
  • Se quiser remover um subconjunto da 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 seção de biblioteca pública existente.

  • Solicitações de exemplo

    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 a computação do Spark publicada para o ambiente

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

  • Solicitação de exemplo

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

  • Resposta de exemplo

    {
    "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 runtime 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 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 espaço de trabalho pela API REST, confira Pools personalizados: Listar pools personalizados do espaço de trabalho

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

  • Solicitação de exemplo

    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 preparo. Depois que o ambiente é publicado com êxito, todas as configurações no estado de preparo tornam-se efetivas.

  • 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 preparo/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 que a publicação entre em vigor. Siga o exemplo abaixo para acionar a publicação.

  • Solicitação de exemplo

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

  • Resposta de exemplo

    {
    "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 chamar a seguinte API para cancelá-la.

  • Solicitação de exemplo

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

Conteúdo relacionado