DataWorks API data source - DataWorks - Centro de documentación de Alibaba Cloud

Puede crear un origen de datos de API REST para escribir datos JSON desde una API RESTful hacia otro origen de datos, como MaxCompute, mediante una tarea de sincronización. Un origen de datos de API REST también puede funcionar como destino para recibir datos de otros orígenes. Este tema describe las capacidades de sincronización de datos del origen de datos de API REST en DataWorks.

Limitaciones

Actualmente, este origen de datos solo es compatible con Serverless resource groups y exclusive resource groups for Data Integration.
No es posible configurar el parámetro de tiempo de espera de la solicitud. El tiempo de espera predeterminado en DataWorks es de 60 segundos. Si la consulta a su API tarda más de 60 segundos en devolver una respuesta, la tarea fallará.

Tipos de columna compatibles

Importante

Al sincronizar datos hacia un destino, solo se admite una estructura de tabla plana y de un solo nivel. No se admiten estructuras de columnas anidadas. Por ejemplo, si una API devuelve una estructura como {data: {user: { id: 1, name:'lily'}, value: 123}}, las columnas deben aplanarse en columnas paralelas como user_id, user_name y value en el destino.

Tipo	Tipo de columna
Entero	LONG, INT
Cadena	STRING
Punto flotante	DOUBLE, FLOAT
Booleano	BOOLEAN
Fecha y hora	DATE

Agregar un origen de datos

Antes de desarrollar una tarea de sincronización en DataWorks, debe agregar el origen de datos necesario siguiendo las instrucciones en Data source configuration. Puede consultar las descripciones de los parámetros en la consola de DataWorks para comprender el significado de cada uno al agregar un origen de datos.

Autenticación del origen de datos

El origen de datos de API REST admite los siguientes tres métodos de autenticación:

No Auth: No se requiere autenticación. Puede acceder directamente a la API. Este método es adecuado para API públicas que no requieren autenticación.
Basic Auth: La autenticación se realiza mediante nombre de usuario y contraseña. Después de seleccionar este método, introduzca el nombre de usuario y la contraseña en la página de configuración.
Token Auth: La autenticación se realiza mediante un token. Después de seleccionar este método, introduzca el access_token obtenido de la API de terceros en el campo de token de la página de configuración.

DataWorks no proporciona una herramienta integrada para obtener tokens de API de terceros. Si su API de terceros utiliza autenticación basada en tokens, como OAuth 2.0, debe obtener el access_token directamente del proveedor de la API. El siguiente ejemplo muestra cómo obtener un token mediante 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'

Una vez obtenido el token, establezca Authentication Method en Token Auth cuando cree un origen de datos de API REST e introduzca el token en el campo correspondiente.

Desarrollar una tarea de sincronización de datos

Para obtener información sobre el punto de entrada y el procedimiento para configurar una tarea de sincronización, consulte las siguientes guías de configuración.

Configurar una tarea de sincronización por lotes de tabla única

Para conocer el procedimiento, consulte Configure a batch synchronization task by using the codeless UI y Configure a batch synchronization task by using the code editor.
Para ver todos los parámetros y una demostración de script en modo script, consulte Appendix: Script demo and parameter description.

Ejemplos

Preguntas frecuentes

¿Solo puedo especificar el número de solicitudes de paginación?
- Respuesta: Sí.
¿Se admite la paginación automática? Por ejemplo, detener la paginación cuando la solicitud no devuelve datos.
- Respuesta: No. De lo contrario, no se puede realizar la fragmentación basada en divisiones.
Si especifico más páginas de paginación de las que existen realmente, lo que provoca datos vacíos en las páginas restantes, ¿cómo maneja esto el sistema?
- Respuesta: Cuando las páginas restantes devuelven datos vacíos, equivale a una consulta SQL que no devuelve resultados. El sistema continuará consultando el siguiente registro.
¿El sistema admite analizar sintácticamente solo un nivel de datos JSON?
- Respuesta: Sí. No se realiza un análisis sintáctico de niveles más profundos.
¿Cómo configuro un tipo de datos que no sea matriz para una API REST en Data Integration de DataWorks?
- Respuesta: Asegúrese de que, en la sección reader de parameter, dataPath apunte a la ruta de los datos que no son matriz. Por ejemplo: dataPath:"data.list". Esto ayuda al plugin a localizar correctamente las columnas de datos que desea leer. Luego, establezca dataMode en multiData. Esto indica que DataWorks procesará los datos como múltiples registros individuales, incluso si no tienen formato de matriz en los datos de origen.
  
  Nota
  Tenga en cuenta que, en el modo multiData, la configuración de column ya no aplica. Debe especificar directamente la ruta de los datos en dataPath.
  
  A continuación se muestra un ejemplo de configuración de un tipo de datos que no es matriz para la API REST en Data Integration:
```
reader: {
  name: "restapi",
  parameter: {
    dataPath: "data.list",
    dataMode: "multiData",
    // Other parameters
  }
}
```

Apéndice: Demostración de script y descripción de parámetros

Configurar una tarea de sincronización por lotes mediante el editor de código

Si desea configurar una tarea de sincronización por lotes mediante el editor de código, debe configurar los parámetros relacionados en el script según los requisitos unificados de formato de script. Para obtener más información, consulte Script mode configuration. La siguiente información describe los parámetros que debe configurar para los orígenes de datos al utilizar el editor de código para una tarea de sincronización por lotes.

Demostración de script del lector

A continuación se muestra un ejemplo 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"
            }
        ]
    }
}

La configuración en modo script se describe a continuación:

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 del script del lector

Nota

Los siguientes parámetros intervienen en el proceso de agregar un origen de datos y configurar un nodo de tarea de Data Integration.

El plugin actual no admite parámetros de programación.

Parámetro	Descripción	Obligatorio	Valor predeterminado
url	La URL de la API RESTful.	Sí	N/A
dataMode	El formato de los datos JSON devueltos por la solicitud a la API RESTful. oneData: Recupera un solo registro del JSON devuelto. multiData: Recupera una matriz JSON del JSON devuelto y pasa múltiples registros al escritor.	Sí	N/A
responseType	El formato de datos de la respuesta. Actualmente, solo se admite el formato JSON.	Sí	JSON
column	La lista de columnas que se van a leer. El parámetro type especifica el tipo de dato de los datos de origen, y el parámetro name especifica la ruta JSON desde la cual se recuperan los datos de la columna actual. Puede especificar la información de las columnas de la siguiente manera. "column":[{"type":"long","name":"a.b" //Retrieve data from path a.b},{"type":"string","name":"a.c"//Retrieve data from path a.c}] Para cada columna que especifique, type y name son obligatorios.	Sí	N/A
dataPath	La ruta a un único objeto JSON o matriz JSON en la respuesta.	No	N/A
method	El método de solicitud. Se admiten GET y POST.	Sí	N/A
socketTimeout	El tiempo de espera del socket para acceder a la API RESTful, en milisegundos.	No	60000
customHeader	La información de encabezado que se pasa a la API RESTful.	No	N/A
parameters	La información de parámetros que se pasa a la API RESTful. Para el método GET, introduzca `abc=1&def=1`. Para el método POST, introduzca parámetros JSON.	No	N/A
dirtyData	Especifica cómo manejar los datos cuando no se encuentran datos en la ruta JSON de columna especificada. dirty: Cuando no se encuentra una columna durante el análisis sintáctico de datos, el registro se marca como datos erróneos. null: Cuando no se encuentra una columna durante el análisis sintáctico de datos, el valor de la columna se establece en null.	Sí	dirty
requestTimes	El número de veces que se solicitarán datos a la API RESTful. single: Envía solo una solicitud. multiple: Envía múltiples solicitudes.	Sí	single
requestParam	Cuando requestTimes se establece en multiple, debe especificar el parámetro de bucle, como pageNumber. El plugin itera sobre el parámetro pageNumber basándose en los valores de startIndex, endIndex y step, y lo pasa a la API RESTful para realizar múltiples solicitudes.	No	N/A
startIndex	El índice inicial de las solicitudes en bucle. El índice inicial es inclusivo.	No	N/A
endIndex	El índice final de las solicitudes en bucle. El índice final es inclusivo.	No	N/A
step	El tamaño del paso de las solicitudes en bucle.	No	N/A
authType	El método de autenticación. Valores válidos: Basic Auth: Autenticación básica. Si la API del origen de datos admite autenticación con nombre de usuario y contraseña, seleccione este método. Luego, configure el nombre de usuario y la contraseña. Durante la integración de datos, las credenciales se envían al endpoint RESTful mediante el protocolo Basic Auth para su autenticación. Token Auth: Autenticación basada en token. Si la API del origen de datos admite autenticación basada en token, seleccione este método. Luego, configure un valor de token fijo. Durante la integración de datos, el token se pasa en el encabezado de la solicitud para su autenticación. Por ejemplo: {"Authorization":"Bearer TokenXXXXXX"}. Nota Para usar un método de cifrado personalizado, puede utilizar el método de autenticación `Token` y proporcionar la información de autenticación cifrada como `AuthToken`.	No	N/A
authUsername/authPassword	El nombre de usuario y la contraseña para la autenticación Basic Auth.	No	N/A
authToken	El token para la autenticación Token Auth.	No	N/A
accessKey/accessSecret	La información de la cuenta para la autenticación de firma de API de Alibaba Cloud.	No	N/A

Demostración de script del escritor

{ "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 del script del escritor

Parámetro	Descripción	Obligatorio	Valor predeterminado
url	La URL de la API RESTful.	Sí	N/A
dataMode	El formato de los datos JSON que se pasan a través de la solicitud RESTful. oneData: Envía solo un registro por solicitud. El número de solicitudes es igual al número de registros. multiData: Envía un lote de registros por solicitud. El número de solicitudes está determinado por el número de tareas divididas en el lado del lector.	Sí	N/A
column	La lista de rutas de columnas para generar datos JSON. El parámetro type especifica el tipo de dato de los datos de origen, y el parámetro name especifica la ruta JSON donde se colocan los datos de la columna actual. Puede especificar la información de las columnas de la siguiente manera. "column":[{"type":"long","name":"a.b" //Place column data to path a.b},{"type":"string","name":"a.c"//Place column data to path a.c}] Nota Para cada columna que especifique, type y name son obligatorios.	Sí	N/A
dataPath	La ruta del objeto JSON donde se coloca el resultado de los datos.	No	N/A
method	El método de solicitud. Se admiten POST y PUT.	Sí	N/A
customHeader	La información de encabezado que se pasa a la API RESTful.	No	N/A
authType	El método de autenticación. Basic Auth: Autenticación básica. Si la API del origen de datos admite autenticación con nombre de usuario y contraseña, seleccione este método. Luego, configure el nombre de usuario y la contraseña. Durante la integración de datos, las credenciales se envían al endpoint RESTful mediante el protocolo Basic Auth para su autenticación. Token Auth: Autenticación basada en token. Si la API del origen de datos admite autenticación basada en token, seleccione este método. Luego, configure un valor de token fijo. Durante la integración de datos, el token se pasa en el encabezado de la solicitud para su autenticación. Por ejemplo: {"Authorization":"Bearer TokenXXXXXX"}. Nota Para usar un método de cifrado personalizado, puede utilizar el método de autenticación `Token` y proporcionar la información de autenticación cifrada como `AuthToken`.	No	N/A
authUsername/authPassword	El nombre de usuario y la contraseña para la autenticación Basic Auth.	No	N/A
authToken	El token para la autenticación Token Auth.	No	N/A
accessKey/accessSecret	La información de la cuenta para la autenticación de firma de API de Alibaba Cloud.	No	N/A
batchSize	El número máximo de registros por solicitud cuando dataMode se establece en multiData.	Sí	512