DataWorks API data source - DataWorks: Central de Documentação do Alibaba Cloud

Limitações

Atualmente, esta fonte de dados suporta apenas Grupos de recursos Serverless e grupos de recursos exclusivos para Data Integration.
Não é possível configure o parâmetro de tempo limite da requisição. O tempo limite padrão no DataWorks é de 60 s. Se a consulta à API demorar mais de 60 s para retornar uma resposta, a tarefa falhará.

Tipos de coluna suportados

Importante

Ao sincronizar dados para um destino, apenas uma estrutura de tabela plana e de nível único é suportada. Estruturas de colunas aninhadas não são aceitas. Por exemplo, se uma API retornar uma estrutura como {data: {user: { id: 1, name:'lily'}, value: 123}}, as colunas devem ser achatadas em colunas paralelas, como user_id, user_name e value, no destino.

Tipo	Tipo de coluna
Inteiro	LONG, INT
String	STRING
Ponto flutuante	DOUBLE, FLOAT
Booleano	BOOLEAN
Data e hora	DATE

Adicionar uma fonte de dados

Antes de desenvolver uma tarefa de sincronização no DataWorks, adicione a fonte de dados necessária seguindo as instruções em Gerenciamento de fontes de dados. Consulte as descrições dos parâmetros no console do DataWorks para entender o significado de cada parâmetro ao adicionar uma fonte de dados.

Autenticação da fonte de dados

A fonte de dados REST API suporta os três métodos de autenticação a seguir:

No Auth: Nenhuma autenticação é necessária. Acesse a API diretamente. Este método é adequado para APIs públicas que não exigem autenticação.
Basic Auth: A autenticação ocorre mediante nome de usuário e senha. Após selecione este método, insira o nome de usuário e a senha na página de configuração.
Token Auth: A autenticação usa um token. Ao escolher esta opção, insira o access_token obtido da API de terceiros no campo de token na página de configuração.

O DataWorks não fornece uma ferramenta integrada para obter tokens de APIs de terceiros. Caso sua API utilize autenticação baseada em token, como OAuth 2.0, obtenha o access_token diretamente com o provedor da API. O exemplo abaixo demonstra como obter um token usando curl:

curl -X POST https://api.example.com/oauth/token \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

Após obter o token, defina Authentication Method como Token Auth ao crie a fonte de dados REST API e insira o token no campo correspondente.

Desenvolver uma tarefa de sincronização de dados

Para informações sobre o ponto de entrada e o procedimento de configuração de uma tarefa de sincronização, consulte os guias a seguir.

Configurar uma tarefa de sincronização em lote de tabela única

Para o procedimento, visualize Configurar uma tarefa de sincronização em lote usando a UI sem código e Configurar uma tarefa de sincronização em lote usando o editor de código.
Para obter todos os parâmetros e um exemplo de script no modo de script, consulte Apêndice: Exemplo de script e descrição de parâmetros.

Exemplos

Perguntas frequentes

É possível especifique apenas o número de requisições de paginação?
- Resposta: Sim.
A paginação automática é suportada? Por exemplo, parar de paginar quando a requisição não retornar dados.
- Resposta: Não. Caso contrário, o particionamento baseado em divisão não pode ser executado.
Se eu especifique mais páginas de paginação do que realmente existem, causando dados vazios nas páginas restantes, como o sistema lida com isso?
- Resposta: Quando as páginas restantes retornam dados vazios, o comportamento equivale a uma consulta SQL sem resultados. O sistema continuará a consultar o próximo registro.
O sistema suporta a análise de apenas um nível de dados JSON?
- Resposta: Sim. Análises de níveis mais profundos não são realizadas.
Como configuro um tipo de dados não array para uma REST API no DataWorks Data Integration?
- Resposta: Na seção reader de parameter, defina dataPath para o caminho dos dados não array. Exemplo: dataPath:"data.list". Isso ajuda o plug-in a localizar corretamente as colunas de dados que você deseja ler. Em seguida, defina dataMode como multiData. Assim, o DataWorks processará os dados como múltiplos registros individuais, mesmo que não estejam em formato de array nos dados de source.
  
  Nota
  Observe que, no modo multiData, a configuração de column deixa de ser aplicável. Especifique diretamente o caminho dos dados em dataPath.
  
  Visualize abaixo um exemplo de configuração de um tipo de dados não array para a REST API no Data Integration:
```
reader: {
  name: "restapi",
  parameter: {
    dataPath: "data.list",
    dataMode: "multiData",
    // Other parameters
  }
}
```

Apêndice: Exemplo de script e descrição de parâmetros

Configurar uma tarefa de sincronização em lote usando o editor de código

Para configure uma tarefa de sincronização em lote com o editor de código, defina os parâmetros relevantes no script conforme os requisitos unificados de formato de script. Para mais informações, consulte Configuração no modo de script. As informações a seguir descrevem os parâmetros obrigatórios para fontes de dados ao configure uma tarefa de sincronização em lote pelo editor de código.

Exemplo de script do Reader

Confira o seguinte exemplo de script:

{
    "type":"job",
    "version":"2.0",
    "steps":[
        {
            "stepType":"restapi",
            "parameter":{
                "url":"http://127.0.0.1:5000/get_array5",
                "dataMode":"oneData",
                "responseType":"json",
                "column":[
                    {
                        "type":"long",
                        "name":"a.b"  //Find data from the a.b path
                    },
                    {
                        "type":"string",  //Find data from the a.c path
                        "name":"a.c"
                    }
                ],
                "dirtyData":"null",
                "method":"get",
                "socketTimeout":"60000",
                "defaultHeader":{
                    "X-Custom-Header":"test header"
                },
                "customHeader":{
                    "X-Custom-Header2":"test header2"
                },
                "parameters":"abc=1&amp;def=1"
            },
            "name":"restapireader",
            "category":"reader"
        },
        {
            "stepType":"stream",
            "parameter":{

            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":""
        },
        "speed":{
            "throttle":true,  //When throttle is set to false, the mbps parameter does not take effect, indicating no throttling. When throttle is set to true, throttling is enabled.
            "concurrent":1,  //Job concurrency.
            "mbps":"12"//Throttling. Here 1 mbps = 1 MB/s.
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

A configuração no modo de script é descrita da seguinte forma:

After the RESTful API plugin sends an HTTP(S) request, it receives a response body (the body is a JSON object). The dataPath parameter specifies the JSON path to extract data from the body. Here are two examples:

Using the following API response body as an example, the business data is in DATA, and the API returns multiple rows of data at once (DATA is an array):
{
    "HEADER": {
        "BUSID": "bid1",
        "RECID": "uuid",
        "SENDER": "dc",
        "RECEIVER": "pre",
        "DTSEND": "202201250000"
    },
    "DATA": [
        {
            "SERNR": "sernr1"
        },
        {
            "SERNR": "sernr2"
        }
    ]
}

To extract multiple rows of data from DATA as multiple sync records, configure column as "column": [ "SERNR" ], dataMode as "dataMode": "multiData", and dataPath as "dataPath": "DATA".

Using the following API response body as an example, the business data is in content.DATA, and the API returns one row of data at a time (DATA is an object):
{
    "HEADER": {
        "BUSID": "bid1",
        "RECID": "uuid",
        "SENDER": "dc",
        "RECEIVER": "pre",
        "DTSEND": "202201250000"
    },
    "content": {
        "DATA": {
            "SERNR": "sernr2"
        }
    }
}

To extract one row of data from content.DATA as a single sync record, configure column as "column": [ "SERNR" ], dataMode as "dataMode": "oneData", and dataPath as "dataPath": "content.DATA".

Parâmetros do script do Reader

Nota

Os parâmetros a seguir estão envolvidos no processo de adição de uma fonte de dados e na configuração de um nó de tarefa do Data Integration.

O plug-in atual não suporta parâmetros de agendamento.

Parâmetro	Descrição	Obrigatório	Valor padrão
url	A URL da API RESTful.	Sim	N/A
dataMode	O formato dos dados JSON retornados pela requisição à API RESTful. oneData: Recupera um único registro do JSON retornado. multiData: Recupera um array JSON do retorno e passa múltiplos registros para o writer.	Sim	N/A
responseType	O formato de dados da resposta. Atualmente, apenas o formato JSON é suportado.	Sim	JSON
column	A lista de colunas a serem lidas. O parâmetro type define o tipo de dado da source, enquanto name indica o caminho JSON de onde os dados da coluna serão extraídos. Especifique as informações das colunas da seguinte forma: "column":[{"type":"long","name":"a.b" //Recuperar dados do caminho a.b},{"type":"string","name":"a.c"//Recuperar dados do caminho a.c}] Para cada coluna especificada, type e name são obrigatórios.	Sim	N/A
dataPath	O caminho para um único objeto JSON ou array JSON na resposta.	Não	N/A
method	O método de requisição. GET e POST são suportados.	Sim	N/A
socketTimeout	O tempo limite do socket para acessar a API RESTful, em milissegundos.	Não	60000
customHeader	As informações de cabeçalho passadas para a API RESTful.	Não	N/A
parameters	As informações de parâmetros passadas para a API RESTful. Para o método GET, insira `abc=1&def=1`. Para o método POST, insira parâmetros JSON.	Não	N/A
dirtyData	Define como lidar com dados quando nenhum dado é encontrado no caminho JSON da coluna especificada. dirty: Se uma coluna não for encontrada durante a análise dos dados, o registro é marcado como dado sujo. null: Se uma coluna não for encontrada durante a análise dos dados, o valor da coluna é definido como null.	Sim	dirty
requestTimes	O número de vezes para solicitar dados da API RESTful. single: Envia apenas uma requisição. multiple: Envia múltiplas requisições.	Sim	single
requestParam	Quando requestTimes está definido como multiple, especifique o parâmetro de loop, como pageNumber. O plug-in itera sobre o parâmetro pageNumber com base nos valores de startIndex, endIndex e step, passando-o para a API RESTful em múltiplas requisições.	Não	N/A
startIndex	O índice inicial das requisições em loop. O índice inicial é inclusivo.	Não	N/A
endIndex	O índice final das requisições em loop. O índice final é inclusivo.	Não	N/A
step	O tamanho do passo das requisições em loop.	Não	N/A
authType	O método de autenticação. Valores válidos: Basic Auth: Autenticação básica. Se a API da fonte de dados suportar autenticação com nome de usuário e senha, selecione este método. Em seguida, configure o nome de usuário e a senha. Durante a integração de dados, as credenciais são enviadas ao endpoint RESTful por meio do protocolo Basic Auth para autenticação. Token Auth: Autenticação baseada em token. Se a API da fonte de dados suportar autenticação baseada em token, selecione este método. Depois, configure um valor fixo para o token. Durante a integração de dados, o token é passado no cabeçalho da requisição para autenticação. Exemplo: {"Authorization":"Bearer TokenXXXXXX"}. Nota Para usar um método de criptografia personalizado, utilize o método de autenticação `Token` e forneça as informações de autenticação criptografadas como `AuthToken`.	Não	N/A
authUsername/authPassword	O nome de usuário e a senha para autenticação Basic Auth.	Não	N/A
authToken	O token para autenticação Token Auth.	Não	N/A
accessKey/accessSecret	As informações da conta para autenticação por assinatura da API do Alibaba Cloud.	Não	N/A

Exemplo de script do Writer

{ "type":"job", "version":"2.0", "steps":[ { "stepType":"stream", "parameter":{ }, "name":"Reader", "category":"reader" }, { "stepType":"restapi", "parameter":{ "url":"http://127.0.0.1:5000/writer1", "dataMode":"oneData", "responseType":"json", "column":[ { "type":"long", //Place column data to path a.b "name":"a.b" }, { "type":"string", //Place column data to path a.c "name":"a.c" } ], "method":"post", "defaultHeader":{ "X-Custom-Header":"test header" }, "customHeader":{ "X-Custom-Header2":"test header2" }, "parameters":"abc=1&def=1", "batchSize":256 }, "name":"restapiwriter", "category":"writer" } ], "setting":{ "errorLimit":{ "record":"0" //The error count. }, "speed":{ "throttle":true,//If throttle is set to false, the mbps parameter does not take effect, which means throttling is disabled. If throttle is set to true, throttling is enabled. "concurrent":1, //The concurrency of the job. "mbps":"12"//Throttling. 1 mbps = 1 MB/s. } }, "order":{ "hops":[ { "from":"Reader", "to":"Writer" } ] } }

Parâmetros do script do Writer

Parâmetro	Descrição	Obrigatório	Valor padrão
url	A URL da API RESTful.	Sim	N/A
dataMode	O formato dos dados JSON transmitidos pela requisição RESTful. oneData: Envia apenas um registro por requisição. O número de requisições é igual ao número de registros. multiData: Envia um lote de registros por requisição. O número de requisições é determinado pela quantidade de tarefas divididas no lado do reader.	Sim	N/A
column	A lista de caminhos de colunas para gerar dados JSON. O parâmetro type define o tipo de dado da source, enquanto name indica o caminho JSON onde os dados da coluna atual serão colocados. Especifique as informações das colunas da seguinte forma: "column":[{"type":"long","name":"a.b" //Colocar dados da coluna no caminho a.b},{"type":"string","name":"a.c"//Colocar dados da coluna no caminho a.c}] Nota Para cada coluna especificada, type e name são obrigatórios.	Sim	N/A
dataPath	O caminho do objeto JSON onde o resultado dos dados será colocado.	Não	N/A
method	O método de requisição. POST e PUT são suportados.	Sim	N/A
customHeader	As informações de cabeçalho passadas para a API RESTful.	Não	N/A
authType	O método de autenticação. Basic Auth: Autenticação básica. Se a API da fonte de dados suportar autenticação com nome de usuário e senha, selecione este método. Em seguida, configure o nome de usuário e a senha. Durante a integração de dados, as credenciais são enviadas ao endpoint RESTful por meio do protocolo Basic Auth para autenticação. Token Auth: Autenticação baseada em token. Se a API da fonte de dados suportar autenticação baseada em token, selecione este método. Depois, configure um valor fixo para o token. Durante a integração de dados, o token é passado no cabeçalho da requisição para autenticação. Exemplo: {"Authorization":"Bearer TokenXXXXXX"}. Nota Para usar um método de criptografia personalizado, utilize o método de autenticação `Token` e forneça as informações de autenticação criptografadas como `AuthToken`.	Não	N/A
authUsername/authPassword	O nome de usuário e a senha para autenticação Basic Auth.	Não	N/A
authToken	O token para autenticação Token Auth.	Não	N/A
accessKey/accessSecret	As informações da conta para autenticação por assinatura da API do Alibaba Cloud.	Não	N/A
batchSize	O número máximo de registros por requisição quando dataMode está definido como multiData.	Sim	512