Partilhar via

Atualização da API de trabalhos 2.1 para 2.2

  • Artigo

Este artigo detalha atualizações e aprimoramentos para a funcionalidade na versão 2.2 da API de trabalhos. Ele inclui informações para ajudá-lo a update os seus clientes de API existentes a funcionarem com esta nova versão. Essas atualizações incluem enfileiramento padrão de trabalhos 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 de API e clientes, 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 Actualizando da API de Empregos 2.0 para 2.1.

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

Os trabalhos são enfileirados por padrão

O enfileiramento de tarefas é um recurso opcional que impede que tarefas sejam saltadas quando os recursos não estão disponíveis para a execução. O enfileiramento de trabalhos é suportado nas versões 2.0, 2.1 e 2.2 da API de trabalhos, com as seguintes diferenças na manipulação padrão do enfileiramento:

  • Para trabalhos criados com a API de Trabalhos 2.2, a fila é habilitada por padrão. Você pode desativar a fila definindo o campo queue para false nos corpos de solicitação ao criar ou update um trabalho.
  • 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, deve-se habilitar o enfileiramento definindo o campo queue para true nos corpos das solicitações ao criar ou update um trabalho.

Você pode habilitar ou desabilitar a fila quando criar umde trabalho, update parcialmente umde trabalho ou update todas as configurações de trabalho.

Consulte Fila de trabalhos.

Suporte para a paginação de listas extensas de tarefas e execuções 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, parameters, job_clusters ou ambientes são limitados a 100 elementos por resposta. Se mais de 100 values estiverem disponíveis, o corpo da resposta incluirá um campo next_page_token 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 para as respostas às solicitações List job e List job runs foi introduzida com o Jobs API 2.1.

A seguir está um exemplo de corpo de resposta de uma solicitação de Get a single job para um projecto com mais de 100 tarefas. 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 set de resultados, set o parâmetro de consulta page_token na próxima solicitação para o valor retornado no campo next_page_token. Por exemplo, /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

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

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

Alterações aos pedidos de List jobs e List job runs

Para as tarefas List e as execuções de tarefas List, 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 mais resultados estão disponíveis. Caso contrário, a funcionalidade para paginar resultados permanece inalterada.

Para evitar grandes corpos de resposta, as matrizes de tasks e job_clusters de nível superior para cada tarefa são omitidas das respostas por padrão. Para incluir essas matrizes para cada trabalho incluído no corpo de resposta para essas solicitações, adicione o parâmetro expand_tasks=true à solicitação. Quando o expand_tasks está habilitado, um máximo de 100 elementos são retornados nas matrizes tasks e job_clusters. Se qualquer uma dessas matrizes tiver mais de 100 elementos, um campo has_more (não confundir com o campo de has_more de nível raiz que é removido) dentro do objeto job é set para true. No entanto, apenas os primeiros 100 elementos são acessíveis. Não é possível recuperar tarefas adicionais ou clusters após os primeiros 100 com a solicitação de trabalhos List. Para buscar mais elementos, use as solicitações que retornam um único trabalho ou uma única execução de trabalho. As atualizações que suportam a paginação de grandes campos de resposta são discutidas nas seções a seguir.

Get um único trabalho

Na API de Trabalhos 2.2, o Get uma solicitação única de emprego para recuperar detalhes sobre um único trabalho agora oferece suporte à paginação dos campos tasks e job_clusters quando o tamanho de qualquer campo exceder cem elementos. Use o campo next_page_token na raiz do objeto para determinar se mais resultados estão disponíveis. O valor desse campo é então usado como o valor para o parâmetro de consulta page_token em solicitações subsequentes. Os campos de matriz com menos de 100 elementos em uma página ficarão vazios nas páginas subsequentes.

Get uma única corrida

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

A API de Jobs 2.2 também adiciona o parâmetro de consulta only_latest a esse ponto de extremidade para habilitar a exibição apenas das últimas tentativas de execução na matriz tasks. Quando o parâmetro only_latest é true, todas as execuções substituídas por uma nova tentativa ou um reparo são omitidas da resposta.

Quando o run_id se refere a uma tarefa ForEach executada, um campo chamado iterations está presente na resposta. O campo iterations é uma matriz que contém detalhes para todas as execuções da tarefa aninhada da tarefa ForEach e tem as seguintes propriedades:

  • A schema de cada objeto na matriz iterations é a mesma dos objetos na matriz tasks.
  • Se o parâmetro de consulta only_latest for set para true, somente as últimas tentativas de execução serão incluídas na matriz iterations.
  • A paginação é aplicada à matriz iterations em vez da matriz tasks.
  • A matriz tasks ainda está incluída na resposta e inclui a tarefa ForEach executada.

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

Por exemplo, consulte a seguinte resposta para uma tarefa ForEach 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"
}