DataWorks:Criar uma API no modo script

1. Selecionar uma tabela

Clique duas vezes na API para abrir sua página de edição. Na seção Table, configure parâmetros como Data Source Type, Data Source Name e Data Source Environment.

Os parâmetros necessários variam conforme o tipo de fonte de dados. Consulte a interface para mais detalhes.

2. Escrever a consulta SQL

Na seção Edit Query SQL, insira a instrução de consulta SQL.

• Ao selecionar o modo Basic SQL, apenas a sintaxe SQL básica é suportada.

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

  Nota

  Os campos na cláusula SELECT definem os parâmetros de resposta da API. Os parâmetros na cláusula WHERE definem os parâmetros de solicitação da API. Utilize o formato ${} para identificar os parâmetros de solicitação.

  Siga estas regras ao escrever a instrução SQL:

  • Consultas de tabela única, consultas com junção de várias tabelas e consultas aninhadas na mesma fonte de dados são suportadas.

  • Os seguintes itens não são suportados:

    • Múltiplas instruções SQL.

    • Comentários.

    • Instruções que não sejam SELECT, como INSERT, UPDATE e DELETE.

    • A instrução SELECT *. Especifique explicitamente as colunas a serem consultadas.

    • Não coloque a variável ${param} entre aspas. Por exemplo, '${id}' e 'abc${xyz}123' não são suportados. Para isso, use a função concat('abc', ${xyz}, '123').

    • Parâmetros opcionais.

  • Se o nome de uma coluna na cláusula SELECT tiver o prefixo do nome da tabela (por exemplo, t.name), especifique um alias para o parâmetro de resposta (por exemplo, t.name as name).

  • Ao utilizar uma função de agregação (como min, max, sum ou count), especifique um alias para o parâmetro de resposta. Por exemplo, sum(num) as total_num.

  • As variáveis ${param} em uma instrução SQL, inclusive aquelas dentro de strings, são substituídas pelos parâmetros de solicitação. Quando uma variável ${param} é precedida por uma barra invertida (\), ela é tratada como uma string literal.

• Ao selecionar o modo Advanced SQL, há suporte para tags 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>

  As tags MyBatis suportadas no Advanced SQL são if, choose, when, otherwise, trim, foreach e where. Use essas tags para implementar lógicas de consulta complexas, como verificações de valores nulos, travessias de múltiplos valores, consultas dinâmicas a tabelas, ordenação dinâmica e agregações. Para exemplos de código em cenários comuns, consulte Exemplos de Advanced SQL (sintaxe MyBatis).

  Ao usar caracteres especiais em tags MyBatis, escape-os. A tabela a seguir lista os caracteres de escape comuns.

  Caractere especial	Caractere de escape	Descrição
  >	>	Maior que
  >=	>=	Maior ou igual a
  <	&lt;	Menor que
  <=	&lt;=	Menor ou igual a
  &	&amp;	E
  '	&apos;	Aspas simples
  "	&quot;	Aspas duplas

3. Configurar parâmetros de solicitação

No painel direito da página de edição da API, clique em Request Parameters e configure os parâmetros.

Se estiver usando o modo Advanced SQL, adicione manualmente todos os parâmetros de solicitação do script SQL à lista. Isso garante que a documentação da API reflita com precisão os parâmetros necessários.

4. Configurar parâmetros de resposta

No painel direito da página de edição da API, clique em Response Parameters e configure os parâmetros.

1. Configure os parâmetros de resposta.

   Se estiver usando o modo Advanced SQL, adicione manualmente todos os parâmetros de resposta do script SQL à lista. Isso assegura que a documentação da API reflita com precisão os dados retornados.

   Parâmetro	Descrição
   Parameter Name	Nome do parâmetro de resposta. Pode ter até 64 caracteres, deve começar com uma letra e pode conter letras, dígitos, sublinhados (_) e hifens (-).
   Parameter Type	Os tipos de dados suportados são STRING, INT, LONG, FLOAT, Double e Boolean.
   Sample Value	Valor de exemplo para o parâmetro de resposta.
   Description	Breve descrição do parâmetro de resposta.

2. Na seção Advanced Settings, especifique se deseja ativar a Pagination for Return Results.

   • Sem a ativação da Pagination for Return Results, a API retorna no máximo 2.000 registros por padrão.

   • Ative a Pagination for Return Results caso a API possa retornar mais de 2.000 resultados. Após a ativação, acesse a página Resource Group for DataService Studio no painel de navegação direito para definir o número máximo de entradas por página com base no tipo de grupo de recursos.

   Nota

   Se a Pagination for Return Results estiver ativada na aba Response Parameters da página de edição da API e você utilizar uma instrução SQL com cláusula LIMIT na seção Edit Query SQL, a cláusula LIMIT será ignorada. Nesse caso, o número de resultados retornados será determinado pelas configurações da Pagination for Return Results.

   Após ativar a paginação, os seguintes parâmetros comuns são adicionados automaticamente:

   • Parâmetros de solicitação comuns

     • returnTotalNum: determina se o número total de registros de dados deve ser retornado em uma única solicitação.

     • pageNum: número da página atual.

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

   • Parâmetros de resposta comuns

     • pageNum: número da página atual.

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

     • totalNum: número total de registros.

   Nota

   Uma API pode não ter parâmetros de solicitação, mas, nesse caso, ative a Pagination for Return Results.

5. Configurar filtros

Caso precise pré-processar os parâmetros de solicitação ou pós-processar os resultados da consulta, clique em Filter no painel de navegação direito da página de edição da API. Selecione Use Pre-filter ou Use Post-filter conforme necessário. Escolha um Function Type e selecione uma ou mais funções na lista suspensa de pré-filtro ou pós-filtro. As funções são executadas na ordem em que foram adicionadas. Após concluir a configuração, clique em Preview Responses Returned by API Operation para verificar se os resultados atendem às suas expectativas. Para obter mais informações sobre como criar e usar filtros, consulte Criar uma função Aviator e Criar uma função Python.

6. Configurar grupo de recursos de serviço

1. No painel de navegação direito da página de edição da API, clique em Resource Group for DataService Studio. Na seção Resource Group Type, configure o tipo de grupo de recursos a ser usado ao chamar a API.

   É possível selecionar Exclusive Resource Group for DataService Studio ou Shared Resource Group for DataService Studio. Para um Exclusive Resource Group for DataService Studio, selecione o nome do grupo de recursos desejado na lista. O Shared Resource Group for DataService Studio é gerenciado automaticamente pelo DataWorks e não pode ser selecionado por nome.

   Nota

   • Caso o nome do grupo de recursos alvo não esteja na lista, acesse a página Resource Groups, localize o grupo de recursos e clique em Associate Workspace na coluna Operation.

   • Se o grupo de recursos alvo estiver na lista, mas não puder ser selecionado, vá para a página Resource Groups, encontre o grupo de recursos e, na coluna Operation, clique em > Manage Quota . Defina manualmente as Occupied CUs (para grupos de recursos com pagamento conforme o uso) ou as Minimum CUs (para grupos de recursos por assinatura) para a finalidade Data Services.

2. Na área Environment Configuration, defina a Memory, o Timeout e o Maximum Number of Data Records for a Single Request.

   • O tempo limite máximo depende do tipo de grupo de recursos de serviço do DataWorks e da instância do API Gateway selecionados:

     • Instância compartilhada do API Gateway: até 30.000 ms para um Shared Resource Group for DataService Studio e até 30.000 ms para um Exclusive Resource Group for DataService Studio.

     • Instância dedicada do API Gateway: até 30.000 ms para um Shared Resource Group for DataService Studio e até 90.000 ms para um Exclusive Resource Group for DataService Studio.

     Nota

     O tempo de resposta de uma API depende do tempo de execução do SQL. Para evitar falhas na solicitação, defina o Timeout da API com um valor superior ao tempo de execução esperado.

   • O número máximo de entradas por página varia conforme o tipo de grupo de recursos de serviço selecionado:

     • Com um Shared Resource Group for DataService Studio, o limite é de 2.000 registros de dados por página quando a paginação está ativada.

     • Com um Exclusive Resource Group for DataService Studio, o limite sobe para 10.000 registros de dados por página com a paginação ativada.

     Nota

     Não há limite superior para o número total de resultados que uma API pode retornar.

7. Salvar e enviar

Clique no ícone Salvar na barra de ferramentas. Após salvar a API, o grupo de recursos selecionado será utilizado para testes.