DataWorks:Crear una API en modo script

1. Seleccionar una tabla

Haga doble clic en la API para abrir su página de edición. En la sección Table, configure parámetros como Data Source Type, Data Source Name y Data Source Environment.

Los parámetros obligatorios dependen del tipo de origen de datos. Consulte la interfaz de usuario para obtener detalles.

2. Escribir la consulta SQL

En la sección Edit Query SQL, introduzca la instrucción de consulta SQL.

• Si selecciona el modo Basic SQL, solo se admite sintaxis SQL básica.

  SELECT
  name,
  addr AS address,
  SUM(num) as total_num
  FROM
  table_name
  WHERE
  user_id =${uid}

  Nota

  Los campos en la cláusula SELECT definen los parámetros de respuesta de la API. Los parámetros en la cláusula WHERE definen los parámetros de solicitud de la API. Utilice el formato ${} para identificar los parámetros de solicitud.

  Siga estas reglas al escribir la instrucción SQL:

  • Se admiten consultas de tabla única, consultas de unión de varias tablas y consultas anidadas dentro del mismo origen de datos.

  • No se admite lo siguiente:

    • Múltiples instrucciones SQL.

    • Comentarios.

    • Instrucciones que no sean SELECT, como INSERT, UPDATE y DELETE.

    • La instrucción SELECT *. Debe especificar explícitamente las columnas a consultar.

    • No encierre la variable ${param} entre comillas. Por ejemplo, no se admiten '${id}' ni 'abc${xyz}123'. Para lograr esto, utilice la función concat('abc', ${xyz}, '123').

    • Parámetros opcionales.

  • Si el nombre de una columna en la cláusula SELECT tiene como prefijo un nombre de tabla (por ejemplo, t.name), debe especificar un alias para el parámetro de respuesta (por ejemplo, t.name as name).

  • Si utiliza una función de agregación (como min, max, sum o count), debe especificar un alias para el parámetro de respuesta. Por ejemplo, sum(num) as total_num.

  • Las variables ${param} en una instrucción SQL, incluidas aquellas dentro de cadenas, se reemplazan con los parámetros de solicitud. Cuando una variable ${param} está precedida por una barra invertida (\), se trata como una cadena literal.

• Si selecciona el modo Advanced SQL, se admiten etiquetas MyBatis.

  SELECT id, name, create_name
  FROM t_parameter
  <where>
  <if test="'list!=null'">
      id in (
          <foreach collection="list" open="(" close=")" separator="," item="id_num">
              ${id_num}
          </foreach>
      )
  </if>
  </where>

  Las etiquetas MyBatis compatibles en Advanced SQL son if, choose, when, otherwise, trim, foreach y where. Puede utilizar estas etiquetas para implementar lógica de consulta compleja, como comprobaciones de valores nulos, recorridos de múltiples valores, consultas dinámicas de tablas, ordenamiento dinámico y agregaciones. Para ejemplos de código en escenarios comunes, consulte Advanced SQL (MyBatis syntax) examples.

  Al utilizar caracteres especiales en etiquetas MyBatis, debe escapar dichos caracteres. La siguiente tabla enumera los caracteres de escape comunes.

  Carácter especial	Carácter de escape	Descripción
  >	>	Mayor que
  >=	>=	Mayor o igual que
  <	&lt;	Menor que
  <=	&lt;=	Menor o igual que
  &	&amp;	Y
  '	&apos;	Comilla simple
  "	&quot;	Comilla doble

3. Configurar parámetros de solicitud

En el panel derecho de la página de edición de la API, haga clic en Request Parameters y configure los parámetros.

Si utiliza el modo Advanced SQL, agregue manualmente todos los parámetros de solicitud del script SQL a la lista. Esto garantiza que la documentación de la API refleje con precisión los parámetros obligatorios.

4. Configurar parámetros de respuesta

En el panel derecho de la página de edición de la API, haga clic en Response Parameters y configure los parámetros.

1. Configure los parámetros de respuesta.

   Si utiliza el modo Advanced SQL, agregue manualmente todos los parámetros de respuesta del script SQL a la lista. Esto garantiza que la documentación de la API refleje con precisión los datos devueltos.

   Parámetro	Descripción
   Parameter Name	El nombre del parámetro de respuesta. El nombre puede tener hasta 64 caracteres de longitud, debe comenzar con una letra y puede contener letras, dígitos, guiones bajos (_) y guiones (-).
   Parameter Type	Los tipos de datos compatibles son STRING, INT, LONG, FLOAT, Double y Boolean.
   Sample Value	Un valor de ejemplo para el parámetro de respuesta.
   Description	Una breve descripción del parámetro de respuesta.

2. En la sección Advanced Settings, especifique si desea habilitar Pagination for Return Results.

   • Si no habilita Pagination for Return Results, la API devuelve un máximo de 2,000 registros de forma predeterminada.

   • Habilite Pagination for Return Results si la API podría devolver más de 2,000 resultados. Una vez habilitada esta opción, puede ir a la página Resource Group for DataService Studio en el panel de navegación derecho para establecer el número máximo de entradas por página según el tipo de resource group.

   Nota

   Si Pagination for Return Results está habilitado en la pestaña Response Parameters de la página de edición de la API, y usted utiliza una instrucción SQL con una cláusula LIMIT en la sección Edit Query SQL, la cláusula LIMIT se ignora y el número de resultados devueltos se determina mediante la configuración de Pagination for Return Results.

   Después de habilitar la paginación, se agregan automáticamente los siguientes parámetros comunes:

   • Parámetros de solicitud comunes

     • returnTotalNum: determina si se devuelve el número total de registros de datos en una sola solicitud.

     • pageNum: el número de página actual.

     • pageSize: el número de entradas por página.

   • Parámetros de respuesta comunes

     • pageNum: el número de página actual.

     • pageSize: el número de entradas por página.

     • totalNum: el número total de registros.

   Nota

   Una API puede no tener parámetros de solicitud, pero en ese caso, debe habilitar Pagination for Return Results.

5. Configurar filtros

Si necesita preprocesar los parámetros de solicitud o posprocesar los resultados de la consulta, haga clic en Filter en el panel de navegación derecho de la página de edición de la API. Seleccione Use Pre-filter o Use Post-filter según sea necesario. Seleccione un Function Type y luego seleccione una o más funciones de la lista desplegable de prefiltro o posfiltro. Las funciones se ejecutan en el orden en que se agregan. Una vez completada la configuración, puede hacer clic en Preview Responses Returned by API Operation para comprobar si los resultados cumplen con sus expectativas. Para obtener más información sobre cómo crear y utilizar filtros, consulte Create an Aviator function y Create a Python function.

6. Configurar resource group de servicio

1. En el panel de navegación derecho de la página de edición de la API, haga clic en Resource Group for DataService Studio. En la sección Resource Group Type, configure el tipo de resource group que se utilizará al invocar la API.

   Puede seleccionar Exclusive Resource Group for DataService Studio o Shared Resource Group for DataService Studio. Para un Exclusive Resource Group for DataService Studio, puede seleccionar un nombre de resource group objetivo de la lista. Un Shared Resource Group for DataService Studio es gestionado automáticamente por DataWorks y no se puede seleccionar por nombre.

   Nota

   • Si el nombre del resource group objetivo no aparece en la lista, vaya a la página Resource Groups, busque el resource group y haga clic en Associate Workspace en la columna Operation.

   • Si el resource group objetivo aparece en la lista pero no se puede seleccionar, vaya a la página Resource Groups, busque el resource group y, en la columna Operation, haga clic en > Manage Quota . Establezca manualmente las Occupied CUs (para resource groups pay-as-you-go) o las Minimum CUs (para resource groups de suscripción) para el propósito de Data Services.

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

   • El tiempo de espera máximo depende del tipo de resource group de servicio de DataWorks y de la instancia de API Gateway seleccionados:

     • Instancia compartida de API Gateway: hasta 30,000 ms para un Shared Resource Group for DataService Studio y hasta 30,000 ms para un Exclusive Resource Group for DataService Studio.

     • Instancia dedicada de API Gateway: hasta 30,000 ms para un Shared Resource Group for DataService Studio y hasta 90,000 ms para un Exclusive Resource Group for DataService Studio.

     Nota

     El tiempo de respuesta de una API depende de su tiempo de ejecución SQL. Para evitar fallos en las solicitudes, establezca el Timeout de la API en un valor mayor al tiempo de ejecución esperado.

   • El número máximo de entradas por página depende del tipo de resource group de servicio seleccionado:

     • Si selecciona un Shared Resource Group for DataService Studio, el número máximo de registros de datos por página con la paginación habilitada es de 2,000.

     • Si selecciona un Exclusive Resource Group for DataService Studio, el número máximo de registros de datos por página con la paginación habilitada es de 10,000.

     Nota

     No hay límite superior en el número total de resultados que puede devolver una API.

7. Guardar y enviar

Haga clic en el icono de Guardar en la barra de herramientas. Después de guardar la API, el resource group seleccionado se utilizará para las pruebas.