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

Limitações

Atualmente, esta fonte de dados é compatível apenas com Serverless resource groups e exclusive resource groups for Data Integration.
Não é possível configure o parâmetro de tempo limite da solicitaçã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 compatíveis

Importante

Ao sincronizar dados para um destino, apenas uma estrutura de tabela plana e de nível único é compatível. 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 Data source configuration. 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 da REST API oferece suporte aos 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 da REST API e insira o token no campo correspondente.

Desenvolver uma tarefa de sincronização de dados

Para obter 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, consulte Configure a batch synchronization task by using the codeless UI e Configure a batch synchronization task by using the code editor.
Para consultar todos os parâmetros e um exemplo de script no modo script, consulte Appendix: Script demo and parameter description.

Exemplos

Perguntas frequentes

Posso especifique apenas o número de solicitações de paginação?
- Resposta: Sim.
A paginação automática é compatível? Por exemplo, parar a paginação quando a solicitação não retornar dados.
- Resposta: Não. Caso contrário, o particionamento baseado em divisão não poderá ser executado.
Se eu especifique mais páginas de paginação do que realmente existem, resultando em 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 continua consultando o próximo registro.
O sistema é compatível com 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 Data Integration do DataWorks?
- Resposta: Certifique-se de que, na seção reader de parameter, o parâmetro dataPath aponte 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 na origem.
  
  Nota
  Observe que, no modo multiData, a configuração de column deixa de ser aplicável. Especifique o caminho dos dados diretamente 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 configurar uma tarefa de sincronização em lote pelo editor de código, defina os parâmetros relevantes no script conforme os requisitos unificados de formato. Para mais informações, consulte Script mode configuration. As informações a seguir detalham os parâmetros obrigatórios para fontes de dados ao utilizar o 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 script funciona da seguinte maneira:

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 listados abaixo são utilizados durante a adição da fonte de dados e a configuração do nó de tarefa do Data Integration.

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

Parâmetro	Descrição	Obrigatório	Valor padrão
url	URL da API RESTful.	Sim	N/A
dataMode	Formato dos dados JSON retornados pela solicitação à API RESTful. oneData: Recupera um único registro do JSON retornado. multiData: Recupera um array JSON do retorno e encaminha vários registros para o writer.	Sim	N/A
responseType	Formato de dados da resposta. Atualmente, apenas o formato JSON é compatível.	Sim	JSON
column	Lista de colunas a serem lidas. O parâmetro type define o tipo de dado da origem, 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	Caminho para um único objeto JSON ou array JSON na resposta.	Não	N/A
method	Método de solicitação. GET e POST são compatíveis.	Sim	N/A
socketTimeout	Tempo limite do socket para acesso à API RESTful, em milissegundos.	Não	60000
customHeader	Informações de cabeçalho enviadas à API RESTful.	Não	N/A
parameters	Informações de parâmetros enviadas à API RESTful. Para o método GET, insira `abc=1&def=1`. Para o método POST, insira parâmetros em JSON.	Não	N/A
dirtyData	Define como tratar situações em que nenhum dado é encontrado no caminho JSON da coluna especificada. dirty: Se uma coluna não for encontrada durante a análise, o registro é marcado como dado incorreto (dirty data). null: Se uma coluna não for encontrada durante a análise, seu valor é definido como null.	Sim	dirty
requestTimes	Número de vezes que a API RESTful será solicitada. single: Envia apenas uma solicitação. multiple: Envia várias solicitações.	Sim	single
requestParam	Quando requestTimes estiver definido como multiple, especifique o parâmetro de loop, como pageNumber. O plug-in iterará sobre esse parâmetro com base nos valores de startIndex, endIndex e step, passando-o à API RESTful para realizar múltiplas solicitações.	Não	N/A
startIndex	Índice inicial das solicitações em loop. O índice inicial é inclusivo.	Não	N/A
endIndex	Índice final das solicitações em loop. O índice final é inclusivo.	Não	N/A
step	Tamanho do passo para as solicitações em loop.	Não	N/A
authType	Método de autenticação. Valores válidos: Basic Auth: Autenticação básica. Se a API da fonte de dados for compatível com autenticação por nome de usuário e senha, selecione este método e configure as credenciais. Durante a integração de dados, elas serão enviadas ao endpoint RESTful via protocolo Basic Auth. Token Auth: Autenticação baseada em token. Caso a API seja compatível com autenticação por token, escolha esta opção e configure um valor fixo para o token. Na integração de dados, o token será incluído no cabeçalho da solicitação. Exemplo: {"Authorization":"Bearer TokenXXXXXX"}. Nota Para utilizar um método de criptografia personalizado, use a autenticação `Token` e forneça as informações criptografadas como `AuthToken`.	Não	N/A
authUsername/authPassword	Nome de usuário e senha para autenticação Basic Auth.	Não	N/A
authToken	Token para autenticação Token Auth.	Não	N/A
accessKey/accessSecret	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	URL da API RESTful.	Sim	N/A
dataMode	Formato dos dados JSON transmitidos pela solicitação RESTful. oneData: Envia apenas um registro por solicitação. O número de solicitações corresponde ao número de registros. multiData: Envia um lote de registros por solicitação. A quantidade de requisições depende do número de tarefas divididas no lado do reader.	Sim	N/A
column	Lista de caminhos de colunas para gerar dados JSON. O parâmetro type define o tipo de dado da origem, e name indica o caminho JSON onde os dados da coluna serão inseridos. Especifique as informações das colunas assim: "column":[{"type":"long","name":"a.b" //Inserir dados da coluna no caminho a.b},{"type":"string","name":"a.c"//Inserir dados da coluna no caminho a.c}] Nota Para cada coluna especificada, type e name são obrigatórios.	Sim	N/A
dataPath	Caminho do objeto JSON onde o resultado dos dados será colocado.	Não	N/A
method	Método de solicitação. POST e PUT são compatíveis.	Sim	N/A
customHeader	Informações de cabeçalho enviadas à API RESTful.	Não	N/A
authType	Método de autenticação. Basic Auth: Autenticação básica. Se a API da fonte de dados for compatível com autenticação por nome de usuário e senha, selecione este método e configure as credenciais. Durante a integração de dados, elas serão enviadas ao endpoint RESTful via protocolo Basic Auth. Token Auth: Autenticação baseada em token. Caso a API seja compatível com autenticação por token, escolha esta opção e configure um valor fixo para o token. Na integração de dados, o token será incluído no cabeçalho da solicitação. Exemplo: {"Authorization":"Bearer TokenXXXXXX"}. Nota Para utilizar um método de criptografia personalizado, use a autenticação `Token` e forneça as informações criptografadas como `AuthToken`.	Não	N/A
authUsername/authPassword	Nome de usuário e senha para autenticação Basic Auth.	Não	N/A
authToken	Token para autenticação Token Auth.	Não	N/A
accessKey/accessSecret	Informações da conta para autenticação por assinatura da API do Alibaba Cloud.	Não	N/A
batchSize	Número máximo de registros por solicitação quando dataMode está definido como multiData.	Sim	512