Atualização da API do Jobs 2.1 para a 2.2

Este artigo detalha as atualizações e os aprimoramentos da funcionalidade na versão 2.2 do Jobs API e inclui informações para ajudá-lo a atualizar seus clientes API existentes para trabalhar com essa nova versão. Para saber mais sobre as alterações entre as versões 2.0 e 2.1 da API, consulte Atualização da API do Jobs 2.0 para a 2.1.

Como a versão do Jobs API 2.2 aprimora o suporte existente para paginação de grandes conjuntos de resultados, o site Databricks recomenda o uso do Jobs API 2.2 nos scripts e clientes do site API, principalmente quando as respostas podem incluir um grande número de tarefas.

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

Os trabalhos são colocados em fila por padrão

Job O enfileiramento é um recurso opcional que evita que a execução de um trabalho seja ignorada quando o recurso não estiver disponível para a execução. Job O enfileiramento é compatível com as versões 2.0, 2.1 e 2.2 do Jobs API, com as seguintes diferenças no tratamento do enfileiramento em default:

  • Para trabalhos criados com o Jobs API 2.2, o enfileiramento é ativado por default. O senhor pode desativar o enfileiramento definindo o campo queue como false nos corpos da solicitação quando criar ou atualizar um trabalho.

  • Para trabalhos criados com as versões 2.0 e 2.1 do Jobs API, o enfileiramento não é ativado pelo default. Com essas versões, o senhor deve ativar o enfileiramento definindo o campo queue como true nos corpos da solicitação quando criar ou atualizar um trabalho.

O senhor pode ativar ou desativar o enfileiramento ao criar um Job, atualizar parcialmente um Job ou atualizar todas as configurações do Job.

Consulte Job queueing.

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

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

A API 2.2 do Jobs altera a paginação dessas solicitações da seguinte forma:

  • Os campos que representam listas de elementos, como tarefa, parâmetros, trabalho ou ambientes, são limitados a 100 elementos por resposta. Se mais de 100 valores estiverem disponíveis, o corpo da resposta incluirá um campo next_page_token contendo tokens para recuperar a próxima página de resultados.

  • A paginação é adicionada às respostas às solicitações 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 o Jobs API 2.1.

A seguir, um exemplo de corpo de resposta de uma solicitação Get a single job para um Job com mais de 100 tarefas. Para demonstrar a funcionalidade de paginação baseada em tokens, 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 parâmetro de consulta page_token na próxima solicitação com 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 list e get.

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

Para as solicitações List Job e List Job Execution, o parâmetro has_more no nível raiz do objeto de resposta foi 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 de paginar os resultados permanece inalterada.

Para evitar corpos de resposta grandes, as matrizes tasks e job_clusters de nível superior de cada Job são omitidas das respostas por default. Para incluir essas matrizes para cada trabalho incluído no corpo da resposta para essas solicitações, adicione o parâmetro expand_tasks=true à solicitação. Quando expand_tasks está habilitado, no máximo 100 elementos são retornados nas matrizes tasks e job_clusters. Se uma dessas matrizes tiver mais de 100 elementos, um campo has_more (que não deve ser confundido com o campo has_more de nível raiz que foi removido) dentro do objeto job será definido como true.. No entanto, somente os primeiros 100 elementos estarão acessíveis. O senhor não pode recuperar tarefas ou clusters adicionais após os primeiros 100 com a solicitação List Job. Para obter mais elementos, use as solicitações que retornam um único trabalho ou uma única execução de trabalho: Obter um único trabalho e Obter uma única execução.

Obter um único emprego

Em Jobs API 2.2, a solicitação Get a single Job (Obter um único trabalho ) para recuperar detalhes sobre um único trabalho agora suporta a paginação dos campos tasks e job_clusters quando o tamanho de qualquer um dos campos exceder 100 elementos. Use o campo next_page_token na raiz do objeto para determinar se há mais resultados disponíveis. O valor desse campo é então usado como valor para o parâmetro de consulta page_token nas solicitações subsequentes. Os campos de matriz com menos de 100 elementos em uma página ficarão vazios nas páginas subsequentes.

Obter uma única execução

Na API de Jobs 2.2, a solicitação Get a single run (Obter uma única execução ) para recuperar detalhes sobre uma única execução agora é compatível com a paginação dos campos tasks e job_clusters quando o tamanho de um dos campos exceder 100 elementos. Use o campo next_page_token na raiz do objeto para determinar se há mais resultados disponíveis. O valor desse campo é então usado como o valor do parâmetro de consulta page_token nas 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 2.2 do Jobs também adiciona o parâmetro de consulta only_latest a esse endpoint para permitir a exibição apenas das tentativas de execução mais recentes na matriz tasks. Quando o parâmetro only_latest é true, qualquer execução substituída por uma nova tentativa ou um reparo é omitida da resposta.

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

  • O esquema de cada objeto na matriz iterations é o mesmo dos objetos na matriz tasks.

  • Se o parâmetro de consulta only_latest for definido como true, somente as tentativas de execução mais recentes 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 execução da tarefa ForEach.

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

Por exemplo, veja 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"
}