Ir para o conteúdo principal
Documentação
Documentação
Administrator Guide
Última atualização: 2025-09-19
Conceito: API REST para exportação de dados

Conceito: API REST para exportação de dados

Visão geral

A API de exportação de dados no serviço REST Prism permite exportar dados em grande escala de fontes de dados Prism com suporte de tabela.

Principais recursos

  • Crie uma tarefa de exportação de dados para exportar dados de uma fonte de dados Prism com suporte de tabela.
  • Cancelar uma tarefa de exportação de dados específica. O status da tarefa de exportação de dados deve ser Programado ou Em execução.
    • Os usuários em grupos de segurança sem restrição podem visualizar e cancelar todas as tarefas de exportação de dados.
    • Os usuários em um grupo de segurança de autoatendimento podem visualizar e cancelar somente os trabalhos de exportação de dados que eles criaram.
  • Verifique o status da tarefa de exportação de dados.
    • Programado: o Workday programou a execução da tarefa de exportação de dados.
    • Em processamento: o Workday está executando a tarefa de exportação de dados no momento.
    • Êxito: o Workday concluiu a tarefa de exportação de dados e criou um ou mais arquivos de saída contendo os dados exportados.
    • Cancelado: o Workday interrompe a execução da tarefa de exportação de dados a partir da solicitação de um usuário.
    • Falha: o Workday encontrou um erro ao tentar executar a tarefa de exportação de dados.
  • Baixe os arquivos de saída que contêm os dados exportados.
    • Você só pode baixar os arquivos de saída permitidos pelo perfil de segurança do usuário atual.
    • Você pode baixar os arquivos em sequência ou em paralelo. Você pode reduzir o tempo necessário para baixar todos os arquivos de saída baixando-os em paralelo.
    • O desempenho do download depende de:
      • O número de arquivos.
      • O número de downloads simultâneos.
      • A largura de banda da rede entre o cliente de API e o servidor do Workday. Exemplo: se o cliente estiver em uma região geográfica diferente da do servidor, o tempo para baixar os arquivos aumentará.

Casos de uso

Caso de uso
Descrição
Divulgações e relatórios obrigatórios
Em uma programação que pode variar de diária a anual, você precisa extrair grandes volumes de dados financeiros detalhados para períodos específicos do Workday. Após a exportação, você pode enviar os dados para um data posterior em tempo real ou uma ferramenta de relatórios regulamentares. A ferramenta facilita a formatação e o envio de divulgações financeiras para cumprir regulamentos rígidos.
Análises avançadas, ciência de dados e geração de relatórios diversos
Você precisa extrair grandes volumes de dados operacionais e financeiros detalhados para períodos específicos do Workday. Após a exportação, você pode enviar os dados para um corporativo ou um workbench de ciência de dados, onde você pode criar modelos preditivos para, entre outros, os seguintes itens:
  • Clientes e usuários
  • Colaboradores
  • Pesquisa de mercado
  • Desempenho
  • Produtos ou serviços
Suspensões regulamentares e arquivamentos
Você deve atender aos padrões regulamentares e de conformidade arquivando de cinco a sete anos de dados financeiros. Você deve disponibilizar esses dados para autoridades regulatórias e auditorias imediatamente após solicitação, de acordo com os regulamentos e o setor aplicáveis.
Solicitações de auditoria
Para executar uma auditoria completa, você deve solicitar todas as transações, atividades e metadados para determinados saldos durante um período especificado. Esses dados são obrigatórios em uma base mensal, trimestral e anual, bem como para os exercícios anteriores. Você deve exportar um grande número de dados para o banco de dados de auditoria.

Caminho base do URL

Caminho base do locatário 
https://{hostname}/api/prismAnalytics/{version}/{tenantname}/dataExport
Exemplo para criar uma tarefa de exportação de dados: 
https://yourTenantHostName.com/api/prismAnalytics/v3/<TENANT_NAME>/dataExport
Caminho base do gateway de API do Workday Extend
Para aplicativos Workday Extend, use o URL base regional do gateway de API da sua empresa. Consulte Referência: gateways de API do Workday Extend e URLs base de autorização no site do desenvolvedor.
O URL base do gateway de API não inclui o nome do locatário.

Considerações de segurança

Os seguintes domínios na área funcional Prism:
  • Prism Data Export: Execute
    : controla quem pode criar tarefas de exportação de dados.
  • Prism Data Export: Manage
    : controla quem pode visualizar e cancelar tarefas de exportação de dados.

Criando tarefa de exportação de dados

O
POST /dataExport
 O ponto de extremidade facilita a criação de uma tarefa de exportação de dados.
Considerações de segurança:
  • Domínio
    Prism Data Export: Execute
     na área funcional Prism Analytics.
  • Preencha qualquer um destes requisitos de segurança para a tabela da qual você exporta:
    • Domínio
      Prism: Tables Manage
       na área funcional Prism Analytics.
    • Domínio Prism: Tables Owner Manage
       na área funcional Prism Analytics.
    • Permissão
      de visualizador de tabelas
       na tabela.
    • Permissão
      de editor de tabela
       na tabela
    • Permissão
      Proprietário da tabela
      na tabela.
Use esse método para criar uma tarefa de exportação de dados para uma fonte de dados Prism especificada.
Quando você cria uma tarefa de exportação de dados, o Workday gera um ou mais arquivos contendo dados da fonte de dados Prism que você pode baixar no computador local.
No corpo da solicitação, insira um valor para estes parâmetros:
Parâmetro do corpo da função
Tipo
Descrição
entrada
Objeto
Inclua uma consulta WQL que especifique todos os campos a serem exportados de uma fonte de dados Prism.
Use este formato: 
"input": {
"query": " WQL_Query ",
"type": "SQL"
}
Quando você escreve a consulta WQL:
  • Use o alias WQL da fonte de dados Prism e de cada campo.
  • Liste todos os campos que quer incluir. Opcionalmente, você pode renomear um campo usando o operador AS.
  • (Opcional) Você pode filtrar os registros usando uma cláusula WHERE. Você pode filtrar um campo Data comparando-o com outro campo Data. Você não pode filtrar um campo Data comparando-o com um valor de data literal.
  • Você pode exportar qualquer tipo de campo, exceto campos de várias instâncias.
Para obter detalhes sobre como especificar uma consulta válida no parâmetro de entrada, consulte Referência: uso de consulta WQL e diretrizes para exportação de dados.
saída
Objeto
Use este formato: 
"output": {
"type": "CSV_GZIP",
“headers”: true
}
Solicitação de amostra:
POST /dataExport
Corpo da solicitação de amostra:
{
 "input": {
  "query": "SELECT agentCity, GET_DISPLAY_ID(billingCompany) AS
 billing_company, GET_DISPLAY_ID(billingCostCenter) AS billing_CostCenter
 FROM cds_insuranceClaimData WHERE claimAmount > 1000",
  "type": "SQL"
 },
 "output": {
  "type": "CSV_GZIP",
  "headers": true
 }
}
Exemplo de resposta
{
 "createdMoment": "2017-03-17T00:00:00.000Z",
 "status": "Scheduled",
 "input": {
  "query": "SELECT agentCity, GET_DISPLAY_ID(billingCompany) AS
 billing_company, GET_DISPLAY_ID(billingCostCenter) AS billing_CostCenter
 FROM cds_insuranceClaimData WHERE claimAmount > 1000",
  "type": "SQL"
 },
 "id": "b1bd0e1ac5d410001193bf9340050000"
}

Obtendo status da tarefa de exportação de dados

O
GET /dataExport
 O ponto de extremidade facilita a recuperação de todas as tarefas de exportação de dados.
O
GET /dataExport/{id}
 facilita a recuperação de uma tarefa de exportação.
Considerações de segurança:
Domínio
Prism Data Export: Manage
 na área funcional Prism Analytics.
Esse ponto de extremidade retorna os trabalhos de exportação de dados para os quais o usuário atual tem permissão. Quando você recupera uma coleção, use estes parâmetros de consulta opcionais:
Parâmetro de consulta
Descrição
Valor por padrão
Máx.
type
O valor de type determina quais campos de resposta devem ser incluídos.
  • total: retorna todas as informações de exportação de dados.
  • Resumo: retorna uma resposta resumida excluindo a lista de resultados de saída.
resumo
limit
O limite de entradas de dados de objeto incluídas em uma única resposta.
20
1.000
offset
O deslocamento para o primeiro objeto em uma coleção a ser incluído na resposta.
0
Solicitação de amostra:
GET /dataExport
Exemplo de resposta:
A resposta é uma coleção de tarefas de exportação de dados no formato JSON.
Este exemplo de resposta exibe apenas uma tarefa de exportação de dados.
{
 "total": 7,
 "data": [
  {
   "createdMoment": "2023-08-03T22:47:10.929Z",
   "createdBy": {
    "id": "274555853a4446cf8809325243534f34",
    "descriptor": "BLiu / Betty Liu (manager 4300, CostCtrMgr
 30.3, 41200, PayIntPartner; PayPartner, PayAdmin)",
    "fullName": "BLiu / Betty Liu (manager 4300, CostCtrMgr
 30.3, 41200, PayIntPartner; PayPartner, PayAdmin)"
   },
   "status": "Success",
   "input": {
    "query": "SELECT insuranceOfficeState, sourceFileTag,
 sort1, sort2, agentCity, agentCountry, agentNote,
 GET_DISPLAY_ID(billingCompany) AS billing_company,
 GET_DISPLAY_ID(billingCostCenter) AS billing_CostCenter FROM
 cds_insuranceClaimData",
    "type": "SQL"
   },
   "output": {
    "noOfFiles": 4,
    "totalSizeInBytes": 5610214,
    "totalRows": 110408
   },
   "id": "b1bd0e1ac5d4100013ad1f50c6910000"
  },
  ...
 ]
}
Solicitação de amostra para recuperar informações sobre a tarefa de exportação de dados com a ID = b1bd0e1ac5d410001193bf9340050000:
GET /dataExport/b1bd0e1ac5d410001193bf9340050000
Exemplo de resposta: 
{
 "createdMoment": "2023-08-03T22:08:42.928Z",
 "createdBy": {
  "id": "274555853a4446cf8809325243534f34",
  "descriptor": "BLiu / Betty Liu (manager 4300, CostCtrMgr 30.3,
 41200, PayIntPartner; PayPartner, PayAdmin)",
  "fullName": "BLiu / Betty Liu (manager 4300, CostCtrMgr 30.3,
 41200, PayIntPartner; PayPartner, PayAdmin)"
 },
 "status": "Success",
 "input": {
  "query": "SELECT agentCity, GET_DISPLAY_ID(billingCompany) AS
 billing_company, GET_DISPLAY_ID(billingCostCenter) AS billing_CostCenter
 FROM cds_insuranceClaimData WHERE claimAmount > 1000",
  "type": "SQL"
 },
 "output": {
  "createdTime": "2023-08-03T22:08:53.725Z",
  "expirationTime": "2023-08-10T22:08:53.725Z",
  "noOfFiles": 2,
  "totalSizeInBytes": 359680,
  "totalRows": 41301,
  "results": [
   {
    "name":
 "part-00000-70e49bea-487e-4a3e-b43e-be3935e951c1-c000.csv.gz",
    "length": 298913
   },
   {
    "name":
 "part-00001-70e49bea-487e-4a3e-b43e-be3935e951c1-c000.csv.gz",
    "length": 60767
   }
  ]
 },
 "id": "b1bd0e1ac5d410001193bf9340050000"
}

Baixando arquivos de saída

O
GET /dataExport/{id}/results/{fielName}
 O ponto de extremidade facilita o download de arquivos de saída de uma tarefa de exportação de dados.
Especifique:
  • A ID da tarefa de exportação de dados.
  • O nome do arquivo de saída da tarefa de exportação de dados.
O
GET /dataExport/{id}
 O ponto de extremidade fornece os nomes dos arquivos de saída.
Você só pode baixar os arquivos de saída permitidos pelo perfil de segurança do usuário atual. Você pode baixar os arquivos em sequência ou em paralelo.
Considerações de segurança:
Domínio
Prism Data Export: Manage
 na área funcional Prism Analytics.
Solicitação de amostra para fazer download do arquivo part-00000-70e49bea-487e-4a3e-b43e-be3935e951c1-c000.csv.gz:
GET /dataExport/b1bd0e1ac5d410001193bf9340050000/results/part-00000-70e49bea-487e-4a3e-b43e-be3935e951c1-c 000.csv.gz

Cancelamento de uma tarefa de exportação de dados

O
POST /dataExport/{id}/cancel
 O ponto de extremidade facilita o cancelamento de uma tarefa de exportação de dados específica que está programada ou em execução.
Você só pode cancelar tarefas de exportação de dados permitidas pelo perfil de segurança do usuário atual.
Considerações de segurança:
Um destes domínios na área funcional Prism Analytics:
  • Exportação de dados Prism: executar
  • Exportação de dados Prism: gerenciar
Preencha qualquer um destes requisitos de segurança para a tabela da qual você exporta:
  • Domínio
    Prism: Tables Manage
     na área funcional Prism Analytics.
  • Domínio Prism: Tables Owner Manage
     na área funcional Prism Analytics.
  • Permissão de visualizador de tabelas na tabela.
  • Permissão de editor de tabela na tabela
  • Permissão Proprietário da tabela na tabela.
Solicitação de amostra:
Você deve incluir uma cadeia de caracteres JSON vazia { no corpo da solicitação desse método.
Exemplo de solicitação para cancelar uma tarefa de exportação de dados com a ID b1bd0e1ac5d4100018d18abc4ea00000:
POST /dataExport/b1bd0e1ac5d4100018d18abc4ea00000/cancel
Exemplo de resposta:
A resposta contém a tarefa de exportação de dados, incluindo o status atual Cancelado no formato JSON.
{
 "createdMoment": "2023-08-04T00:21:24.914Z",
 "createdBy": {
  "id": "274555853a4446cf8809325243534f34",
  "descriptor": "BLiu / Betty Liu (manager 4300, CostCtrMgr 30.3,
 41200, PayIntPartner; PayPartner, PayAdmin)",
  "fullName": "BLiu / Betty Liu (manager 4300, CostCtrMgr 30.3,
 41200, PayIntPartner; PayPartner, PayAdmin)"
 },
 "status": "Canceled",
 "input": {
  "query": "SELECT agentCity, GET_DISPLAY_ID(billingCompany) AS
 billing_company, GET_DISPLAY_ID(billingCostCenter) AS billing_CostCenter
 FROM cds_insuranceClaimData",
  "type": "SQL"
 },
 "id": "b1bd0e1ac5d4100018d18abc4ea00000"
}

Limitações

  • As tarefas de exportação são tarefas de baixa prioridade e terão precedência mais baixa do que outras tarefas, como publicação.
  • Você não poderá fazer download dos arquivos gerados após 7 dias, pois eles serão excluídos.
  • Estes valores máximos são definidos como grades de proteção para otimizar o desempenho e a confiabilidade do sistema:
    • 1 bilhões de linhas por tarefa de exportação.
    • 1.000 colunas por consulta
  • Solicitações simultâneas de download:
    • Se o limite do sistema for atingido, você receberá uma resposta 503 - HIT_ServER_Limit.
    • Se um locatário exceder seu limite específico, você receberá uma resposta 429 - HIT_TENANT_Limit.
  • Tarefas de exportação simultâneas:
    • Somente uma tarefa de exportação pode ser executada por vez por usuário ou locatário.
    • Quaisquer tarefas de exportação adicionais serão automaticamente enfileiradas até que a tarefa atual seja concluída.

Erros comuns

Erros de validação:
  • Json de entrada malformado.
  • SQL malformado, campos/nome de tabela inválidos, funções sem suporte.
  • Salvaguardas: número de campos > 10.000.
  • Restrições de segurança não atendidas.
Erros de execução
  • Erros do sistema
  • Guias hierárquicos: falha se a extração tem mais de 1B linhas.
Baixar APIs
  • Durante o download, é sempre recomendável que o cliente HTTP tenha novas tentativas devido a problemas imprevistos na rede ou no sistema. Há um limite de taxa aplicado ao número de conexões simultâneas criadas para um locatário e um servidor. Ocasionalmente, você pode ver códigos de status HTTP
    429
     ou
    503
     devido a esses limites impostos. É recomendável que o cliente aguarde algum tempo e tente fazer a solicitação novamente.

Considerações sobre desempenho

Desempenho da extração de dados:
  • O tempo de execução da extração de dados varia dependendo do tipo de dados e do número de linhas e colunas nos dados.
  • O tempo de execução aumenta com o volume de dados.
Desempenho do download:
  • O tempo total de download para todos os tamanhos de arquivo diminui linearmente com o número de processos que baixam os resultados.
  • O desempenho do download também pode ser afetado pela largura de banda da rede e pelo local do servidor do locatário.