Compartir a través de

Administración del entorno a través de API públicas

  • Artículo

La API REST de Microsoft Fabric proporciona un punto de conexión de servicio para las operaciones de creación, lectura, actualización y eliminación (CRUD) de un elemento de Fabric. En este artículo se describen las API de REST del entorno disponibles y su uso.

Importante

Esta característica se encuentra en versión preliminar.

Resumen de las API del entorno disponibles

API Descripción Category
Crear ambiente Crea un entorno nuevo en el área de trabajo. General
Obtener entorno Obtiene los metadatos de un entorno. La respuesta incluye el estado del entorno. General
Actualizar entorno Actualiza los metadatos de un entorno, como el nombre y la descripción. General
Eliminación del entorno Elimina un entorno existente. General
Enumerar entorno en el área de trabajo Obtiene la lista de entornos del área de trabajo. General
Publicar entorno Desencadena la publicación del entorno con los cambios pendientes actuales. General
Cancelación de la publicación Cancela una publicación en curso del entorno General
Obtener proceso de Spark publicado Obtiene las configuraciones de proceso de Spark que están activas. Proceso de Spark
Obtener proceso de Spark de almacenamiento provisional Obtiene todas las configuraciones de proceso de almacenamiento provisional. Las configuraciones de almacenamiento provisional incluyen las configuraciones de proceso publicadas y pendientes. Proceso de Spark
Obtener bibliotecas publicadas Obtiene la lista de bibliotecas que está activa. Bibliotecas
Obtener bibliotecas de almacenamiento provisional Obtiene la lista completa de bibliotecas de almacenamiento provisional. Esta lista incluye las bibliotecas publicadas y pendientes. Bibliotecas
Cargar bibliotecas de almacenamiento provisional Permite agregar una biblioteca personalizada o una o varias bibliotecas públicas al entorno. Bibliotecas
Eliminar bibliotecas de almacenamiento provisional Elimina una biblioteca personalizada de almacenamiento provisional o toda la biblioteca pública. Bibliotecas

Más información sobre las API públicas del entorno en API de elemento: entorno

Casos de uso de API públicas del entorno

Esta sección le guía a través de varios escenarios habituales al tratar con el entorno. En los ejemplos siguientes, puede reemplazar {WORKSPACE_ID} y {ARTIFACT_ID} por los valores correspondientes.

Crear un nuevo entorno

Puede crear un nuevo entorno vacío mediante la API siguiente.

  • Solicitud de ejemplo

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

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

Administración de las bibliotecas de almacenamiento provisional

Puede usar las API de carga/eliminación de las bibliotecas de almacenamiento provisional para administrar la sección de la biblioteca del entorno

Comprobación de las bibliotecas publicadas del entorno

Antes de agregar o eliminar la biblioteca, puede usar la API de obtención de bibliotecas publicadas para comprobar qué bibliotecas están activas actualmente.

  • Solicitud de ejemplo

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

  • Respuesta de muestra

    {
    "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"
}

Carga de las bibliotecas

La API para cargar la biblioteca de almacenamiento provisional acepta un archivo de cada vez. Los tipos de archivo admitidos son .whl, .jar, .tar.gz, .py y environment.yml para la biblioteca pública. Puede especificar el archivo a través del tipo de contenido multipart/form-data.

Nota:

  • Para manipular la biblioteca pública de forma más eficaz, se recomienda encarecidamente componer todas las bibliotecas esperadas de PyPI y Conda en un archivo environment.yml.
  • La API de carga permite un archivo de hasta 200 MB en una solicitud; si la biblioteca supera este límite de tamaño, no se admite actualmente en la API pública.

  • Solicitudes de ejemplo

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

Eliminación de las bibliotecas

Al especificar el nombre del archivo de biblioteca completo con el sufijo de tipo, puede eliminar una biblioteca de cada vez.

Nota:

  • Si especifica environment.yml como archivo que se va a eliminar, se eliminarán todas las bibliotecas públicas.
  • Si desea eliminar un subconjunto de bibliotecas públicas existentes, use cargar biblioteca en su lugar y cargue un environment.yml que contenga solo las bibliotecas previstas. El environment.yml cargado reemplazará por completo la sección de biblioteca pública existente.

  • Solicitudes de ejemplo

    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

Administración del proceso de Spark de almacenamiento provisional

Puede usar la actualización del proceso de Spark de almacenamiento provisional para administrar el proceso de Spark.

Comprobación del proceso de Spark publicado para el entorno

Antes de cambiar las configuraciones del entorno, puede usar la API de obtención del proceso de Spark publicado para comprobar qué configuraciones del proceso de Spark están actualmente activas.

  • Solicitud de ejemplo

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

  • Respuesta de muestra

    {
    "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"
}

Actualización de la configuración de proceso

Puede actualizar el tiempo de ejecución de Spark, cambiar a otro grupo, mejorar la configuración de proceso y agregar o eliminar propiedades de Spark mediante la edición del cuerpo de la solicitud de esta API.

Puede cambiar el grupo adjunto especificando el nombre del grupo y el grupo. Especifique el nombre del grupo como Starter Pool para cambiar el grupo a la configuración predeterminada. Para obtener la lista completa de los grupos personalizados disponibles del área de trabajo por la API de REST, consulte Grupos personalizados: enumerar grupos personalizados del área de trabajo.

Si quiere eliminar una propiedad de Spark existente, debe especificar el valor como null con la clave que quiere eliminar, como se muestra en el ejemplo siguiente.

  • Solicitud de ejemplo

    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"
}

Aplicación de los cambios

Con los siguientes conjuntos de API para publicar los cambios.

Preparación para la publicación

El entorno puede aceptar una publicación de cada vez. Antes de publicar el entorno, puede validar el estado del entorno y hacer una revisión final de los cambios de almacenamiento provisional. Una vez que el entorno se ha publicado correctamente, todas las configuraciones en estado de almacenamiento provisional se vuelven activas.

  • Paso 1: obtención de los metadatos del entorno

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

    En el cuerpo de la respuesta, puede indicar claramente el estado del entorno. Asegúrese de que no haya ninguna publicación en curso antes de ir al paso siguiente.

  • Paso 2: obtención de las bibliotecas de almacenamiento provisional o el proceso de Spark para efectuar una revisión 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

Desencadenamiento de la publicación del entorno

Los cambios realizados en las bibliotecas de almacenamiento provisional y el proceso de Spark se almacenan en caché, pero requieren que la publicación sea efectiva. Siga el ejemplo siguiente para desencadenar la publicación.

  • Solicitud de ejemplo

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

  • Respuesta de muestra

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

Durante la publicación, también puede llamar a la API siguiente para cancelarla.

  • Solicitud de ejemplo

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

Contenido relacionado