Compartilhar via

Atualização da Jobs API 2.1 para 2.2

Este artigo detalha atualizações e aprimoramentos da funcionalidade na versão 2.2 da API de Trabalhos. Ele inclui informações para ajudá-lo a atualizar seus clientes de API existentes para trabalhar com essa nova versão. Essas atualizações incluem o enfileiramento padrão de tarefas e melhor suporte para paginação quando as respostas incluem campos com mais de 100 elementos. Como a versão 2.2 aprimora o suporte existente para paginar grandes conjuntos de resultados, o Databricks recomenda usá-lo para seus scripts e clientes de API, especialmente quando as respostas podem incluir muitas tarefas.

Para saber mais sobre as alterações entre as versões 2.0 e 2.1 da API, consulte Atualização da API de Trabalhos 2.0 para 2.1.

Além das alterações incluídas na versão 2.1 da API de Trabalhos do Lakeflow, a versão 2.2 tem os seguintes aprimoramentos:

As tarefas são enfileiradas por configuração padrão

O enfileiramento de tarefas é um recurso opcional que impede que as tarefas sejam puladas quando os recursos não estiverem disponíveis para a execução. Há suporte para filas de trabalho nas versões 2.0, 2.1 e 2.2 da API de Trabalhos, com as seguintes diferenças no tratamento padrão do enfileiramento:

  • Para trabalhos criados com a API de Trabalhos 2.2, o enfileiramento é habilitado por padrão. Você pode desativar o enfileiramento definindo o campo queue como false nos conteúdos das solicitações ao criar ou atualizar uma tarefa.
  • Para trabalhos criados com as versões 2.0 e 2.1 da API de Trabalhos, o enfileiramento não está habilitado por padrão. Com essas versões, você deve habilitar o enfileiramento definindo o campo queue para true em corpos de solicitação ao criar ou atualizar um trabalho.

Você pode habilitar ou desabilitar o enfileiramento ao criar um trabalho, atualizar parcialmente um trabalho ou atualizar todas as configurações de trabalho.

Consulte o enfileiramento de trabalho.

Suporte para paginação de listas de tarefas longas e listas de execução de tarefas

Para dar suporte a trabalhos com um grande número de tarefas ou execuções de tarefas, a API de Trabalhos 2.2 altera a forma como grandes conjuntos de resultados são retornados para as seguintes solicitações:

A API de Trabalhos 2.2 altera a paginação para essas solicitações da seguinte maneira:

  • Os campos que representam listas de elementos como tarefas, parâmetros, job_clusters ou ambientes são limitados a 100 elementos por resposta. Se mais de 100 valores estiverem disponíveis, o corpo da resposta incluirá um next_page_token campo que contém um token para recuperar a próxima página de resultados.
  • A paginação é adicionada para as respostas às solicitações de Get a single job e Get a single job run. A paginação das respostas às solicitações List job e List job runs foi adicionada com a API de Trabalhos 2.1.

Veja a seguir um exemplo de corpo de resposta de uma Get a single job solicitação para uma tarefa com mais de 100 subtarefas. Para demonstrar a funcionalidade de paginação baseada em token, este exemplo omite a maioria dos campos incluídos no corpo da resposta:

{
  "job_id": 11223344,
  "settings": {
    "tasks": [
      {
        "task_key": "task-1"
      },
      {
        "task_key": "task-2"
      },
      {
        "task_key": "task-..."
      },
      {
        "task_key": "task-100"
      }
    ]
  },
  "next_page_token": "Z29...E="
}

Para recuperar o próximo conjunto de resultados, defina o page_token parâmetro de consulta na próxima solicitação para o valor retornado no next_page_token campo. Por exemplo, /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Se não houver mais resultados disponíveis, o next_page_token campo não será incluído na resposta.

As seções a seguir fornecem mais detalhes sobre as atualizações para cada uma das solicitações list e get.

Alterações nas solicitações List jobs e List job runs

Para as solicitações de listar trabalhos e listar execuções de trabalho, o parâmetro has_more no nível raiz do objeto de resposta é removido. Em vez disso, use a existência do next_page_token para determinar se há mais resultados disponíveis. Caso contrário, a funcionalidade para paginar resultados permanece inalterada.

Para evitar grandes corpos de resposta, os arrays de nível superior tasks e job_clusters de cada trabalho são omitidos das respostas por padrão. Para incluir essas matrizes para cada trabalho incluído no corpo da resposta dessas solicitações, adicione o expand_tasks=true parâmetro à solicitação. Quando expand_tasks estiver habilitado, no máximo 100 elementos serão retornados nas matrizes tasks e job_clusters. Se uma dessas matrizes tiver mais de 100 elementos, um has_more campo (para não ser confundido com o campo de nível has_more raiz removido) dentro do job objeto será definido como true. No entanto, somente os primeiros 100 elementos estarão acessíveis. Você não pode recuperar tarefas ou clusters adicionais após os primeiros 100 com a solicitação de trabalhos de lista . Para buscar mais elementos, use as requisições que retornam um único trabalho ou a execução de um único trabalho. As atualizações que dão suporte à paginação de campos de resposta grandes são discutidas nas seções a seguir.

Conseguir um único emprego

Na API de Trabalhos 2.2, a solicitação Obter um único trabalho para recuperar detalhes sobre um único trabalho agora dá suporte à paginação dos tasks campos e job_clusters quando o tamanho de qualquer campo excede 100 elementos. Use o next_page_token campo na raiz do objeto para determinar se há mais resultados disponíveis. Em seguida, o valor desse campo é usado como o valor do page_token parâmetro de consulta em solicitações subsequentes. Campos de matriz com menos de 100 elementos em uma página estarão vazios nas páginas subsequentes.

Obter uma única execução

Na API de Trabalhos 2.2, a solicitação Obter uma única execução para recuperar detalhes sobre uma única execução agora dá suporte à paginação dos tasks campos e job_clusters quando o tamanho de um dos campos excede 100 elementos. Use o next_page_token campo na raiz do objeto para determinar se há mais resultados disponíveis. Em seguida, o valor desse campo é usado como o valor do parâmetro de consulta page_token em solicitações subsequentes. Campos de matriz com menos de 100 elementos em uma página estarão vazios nas páginas subsequentes.

A Jobs API 2.2 também adiciona o parâmetro de consulta only_latest a esse endpoint para mostrar apenas as tentativas de execução mais recentes na matriz tasks. Quando o parâmetro only_latest é true, quaisquer execuções substituídas por uma repetição ou um reparo são omitidas da resposta.

Quando o run_id refere-se a uma ForEach tarefa, um campo chamado iterations está presente na resposta. O campo iterations é uma matriz que contém detalhes sobre todas as execuções das tarefas aninhadas da tarefa ForEach e possui as seguintes propriedades.

  • O esquema de cada objeto na iterations matriz é o mesmo dos objetos na tasks matriz.
  • Se o only_latest parâmetro de consulta estiver definido como true, somente as tentativas de execução mais recentes serão incluídas na iterations matriz.
  • A paginação é aplicada à iterations matriz em vez da tasks matriz.
  • A tasks matriz ainda está incluída na resposta e inclui a tarefa em execução ForEach.

Para saber mais sobre a ForEach tarefa, consulte a documentação da tarefa ForEach.

Por exemplo, consulte a seguinte resposta para uma ForEach tarefa com alguns campos omitidos:

{
  "job_id": 53,
  "run_id": 759600,
  "number_in_job": 7,
  "original_attempt_run_id": 759600,
  "state": {
    "life_cycle_state": "TERMINATED",
    "result_state": "SUCCESS",
    "state_message": ""
  },
  "cluster_spec": {},
  "start_time": 1595943854860,
  "setup_duration": 0,
  "execution_duration": 0,
  "cleanup_duration": 0,
  "trigger": "ONE_TIME",
  "creator_user_name": "user@databricks.com",
  "run_name": "process_all_numbers",
  "run_type": "JOB_RUN",
  "tasks": [
    {
      "run_id": 759600,
      "task_key": "process_all_numbers",
      "description": "Process all numbers",
      "for_each_task": {
        "inputs": "[ 1, 2, ..., 101 ]",
        "concurrency": 10,
        "task": {
          "task_key": "process_number_iteration"
          "notebook_task": {
            "notebook_path": "/Users/user@databricks.com/process_single_number",
            "base_parameters": {
              "number": "{{input}}"
            }
          }
        },
        "stats": {
          "task_run_stats": {
            "total_iterations": 101,
            "scheduled_iterations": 101,
            "active_iterations": 0,
            "failed_iterations": 0,
            "succeeded_iterations": 101,
            "completed_iterations": 101
          }
        }
      }
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "iterations": [
    {
      "run_id": 759601,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    },
    {
      "run_id": 759602,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "format": "MULTI_TASK",
  "next_page_token": "eyJ..x9"
}
  • Last updated on