DataWorks:Crear una API a partir de un origen de datos (API Gateway)

Comparación de modos

Elección de un modo

• Use el modo asistente: para consultas sencillas en una sola tabla de datos, como filtros de igualdad, coincidencia difusa o rango. Este modo proporciona una interfaz visual sin código para la configuración de la API.

• Use el modo script: para consultas avanzadas, como JOIN de varias tablas, subconsultas anidadas, agregación o condiciones dinámicas con parámetros opcionales.

1. Seleccionar un origen de datos y una tabla

Haga doble clic en la API para abrir su página de edición. En el área Table, configure parámetros como Data Source Type, Data Source Name y Data Source Environment. Los parámetros de configuración varían según el tipo de origen de datos. Consulte la interfaz de usuario para ver los parámetros específicos.

2. Definir la lógica de consulta

La definición de la lógica de consulta difiere entre el modo asistente y el modo script.

3. Configurar parámetros de solicitud

Haga clic en Request Parameters en el panel derecho de la página de edición de la API para configurar los parámetros.

4. Configurar parámetros de respuesta y paginación

Haga clic en Response Parameters en el panel derecho de la página de edición de la API para configurar el nombre del parámetro, el tipo de parámetro, el valor de muestra y la descripción. En el modo Advanced SQL, debe agregar manualmente todos los parámetros de respuesta basándose en su script SQL.

En el área Advanced Settings, especifique si desea habilitar Pagination for Return Results:

• Deshabilitado: la API devuelve un máximo de 2,000 registros de forma predeterminada.

• Habilitado: puede establecer el número máximo de registros por página en la página Resource Group for DataService Studio según el tipo de resource group.

Cuando la paginación está habilitada, el sistema agrega automáticamente los siguientes parámetros comunes:

• Parámetros de solicitud comunes: returnTotalNum (si se devuelve el número total de registros), pageNum (el número de página actual) y pageSize (el número de registros por página).

• Parámetros de respuesta comunes: pageNum, pageSize y totalNum (el número total de registros).

5. Configurar filtros (opcional)

Para preprocesar parámetros de solicitud o posprocesar resultados de consulta, haga clic en Filter en el panel de navegación derecho. Marque la casilla Use Pre-filter o Use Post-filter. A continuación, seleccione un Function Type y elija una función. Puede agregar varias funciones, que se ejecutan en el orden en que se añaden. Para más información sobre cómo crear y utilizar filtros, consulte Create an Aviator function y Create a Python function.

6. Configurar resource groups de servicio

En el panel de navegación derecho, haga clic en Resource Group for DataService Studio para configurar el tipo de resource group para la API.

Puede utilizar un Exclusive Resource Group for DataService Studio o un Shared Resource Group for DataService Studio. Para un resource group de servicio exclusivo, puede seleccionar un resource group objetivo por nombre. Un resource group de servicio público es mantenido automáticamente por DataWorks.

En el área Environment Configuration, puede establecer la Memory, el Timeout y el Maximum Number of Data Records for a Single Request:

• Tiempo de espera: el tiempo de espera no puede exceder los 30,000 ms para instancias compartidas de API Gateway, o los 90,000 ms para resource groups de servicio exclusivo que utilizan instancias dedicadas de API Gateway.

  Nota

  El tiempo de respuesta de la API depende del tiempo de ejecución de SQL. Establezca el valor de tiempo de espera lo suficientemente alto para acomodar esto y evitar fallos en las solicitudes debido a tiempos de espera agotados.

• Número máximo de registros por página: hasta 2,000 para un resource group de servicio público y hasta 10,000 para un resource group de servicio exclusivo. El número total de resultados que una API puede devolver no está limitado.

Ejemplo 1: Controlar el orden de clasificación

El valor de var determina el orden de clasificación.

select col01,col02
from table_name
<choose>
    <when test='var == 1'>
    order by col01
    </when>
    <when test='var == 2'>
    order by col02
    </when>
    <when test='var == 3'>
    order by col01,col02
    </when>
    <when test='var == 4'>
    order by col02,col01
    </when>
</choose>

Parámetro de solicitud: var (Tipo: INT, Obligatorio). Parámetros de respuesta: col01, col02.

Ejemplo 2: Consultar diferentes tablas

Diferentes valores de var determinan qué tabla consultar.

select col01
from
<choose>
 <when test='var == 1'>
 table_name01
 </when>
 <when test='var == 2'>
 table_name02
 </when>
</choose>

Ejemplo 3: Cláusula WHERE dinámica

Las condiciones de consulta se generan dinámicamente según si la colección list está vacía. Si list no es nulo, se genera una condición de consulta que incluye el valor del campo area.

SELECT area_id, area, amount
FROM table_name
<where>
	<if test='list!=null'>
	area in
		<foreach collection="list" open="(" close=")" separator="," item="area">
		#{area}
		</foreach>
	</if>
</where>

Parámetro de solicitud: list (Tipo: STRING_LIST, Obligatorio, Ejemplo: Beijing,Hangzhou). Parámetros de respuesta: area_id, area y amount.

Parámetros opcionales en modo asistente

En el modo asistente, seleccione uid y gender como parámetros de solicitud en el área Select Parameters. A continuación, vaya al panel Request Parameters de la derecha y desmarque la casilla Required correspondiente al parámetro gender.

• Seleccionada: Debe proporcionar un valor para el parámetro al invocar la API. De lo contrario, se genera una excepción de validación de parámetros.

• Desmarcada: Puede decidir si desea pasar un valor para el parámetro. Si no se proporciona ningún valor, el parámetro no se incluye como condición de consulta.

Ejemplos de invocación:

• Escenario 1: Se proporcionan valores tanto para uid como para gender. El sistema ejecuta la siguiente consulta:

  SELECT uid, gender, age_range, zodiac
  FROM ods_user_info_d
  WHERE uid = 0016359810821
  AND gender = 'Female';

• Escenario 2: Se proporciona un valor para uid, pero no para gender. El sistema ejecuta la siguiente consulta:

  SELECT uid, gender, age_range, zodiac
  FROM ods_user_info_d
  WHERE uid = 0016359810821;

Parámetros opcionales en modo script

En el modo SQL avanzado, utilice la etiqueta <if> de MyBatis para implementar la lógica condicional:

SELECT uid, gender, age_range, zodiac
FROM ods_user_info_d
<where>
    <if test='gender!=null'>
    gender = ${gender}
    </if>
    and uid = ${uid}
</where>

• La etiqueta <where> gestiona automáticamente la palabra clave WHERE y elimina los prefijos AND u OR redundantes.

• La etiqueta <if test='gender!=null'> agrega la condición a la consulta solo si se pasa un valor distinto de nulo para el parámetro gender.

• Después de configurar la sentencia SQL, agregue manualmente los parámetros uid y gender en el panel Request Parameters de la derecha, y desmarque la casilla Required del parámetro gender.

El comportamiento es idéntico al del modo asistente: la condición de gender se aplica cuando se proporciona un valor y se ignora cuando se omite.

Configuración de parámetros opcionales