DataWorks:Criar uma API a partir de uma fonte de dados (API Gateway)

Pré-requisitos

• Configure uma fonte de dados na página Workspace Management > Data source management. Para mais detalhes, consulte Configurar uma fonte de dados.

• O serviço de dados requer um grupo de recursos. Em ambiente de produção, recomendamos usar um grupo de recursos serverless. Para mais detalhes, consulte Grupos de recursos e conectividade de rede.

DataService Studio

Faça login no console do DataWorks. Na região desejada, clique em Data Analysis and Service > DataService Studio no painel de navegação à esquerda. Selecione um workspace na lista suspensa e clique em Go to DataService Studio.

Etapa 1: Configurar o API Gateway

Antes de criar um processo de negócios, conclua as tarefas a seguir no console do API Gateway.

1. Acesse o console do API Gateway e ative o API Gateway.

2. No console do API Gateway, crie um grupo de APIs. Um grupo de APIs é uma coleção de APIs para um recurso ou cenário específico e funciona como a unidade básica de gerenciamento de APIs no API Gateway.

   Importante

   A região do API Gateway deve corresponder à região do workspace do DataWorks.

Etapa 2: Criar um processo de negócios

O serviço de dados usa processos de negócios para organizar o desenvolvimento de APIs por domínio de negócio. Cada processo de negócios deve estar vinculado a um grupo de APIs. Crie um processo de negócios antes de gerar uma API.

1. Na página Service Development, clique no ícone e selecione Create Workflow.

2. Na caixa de diálogo Create Workflow, configure os parâmetros.

   Parâmetro	Descrição
   Workflow Name	O nome deve ser exclusivo no workspace. Deve ter entre 4 e 50 caracteres, começar com uma letra ou caractere chinês e pode conter caracteres chineses, letras, dígitos e sublinhados (_).
   API grouping	Selecione o grupo de APIs criado na Etapa 1. Para criar um novo grupo, acesse o console do API Gateway. Importante Após vincular um processo de negócios a um grupo de APIs, não é possível alterar o grupo. Escolha-o com atenção.
   Business Description	Insira uma descrição para o processo de negócios. A descrição não pode exceder 180 caracteres.

3. Clique em Determine. Após criar o processo de negócios, visualize-o na lista Workflow.

Etapa 3: Escolher um modo de API

O DataService Studio permite criar APIs no modo assistente ou no modo script. Ambos os modos compartilham o mesmo processo básico de configuração de API, mas diferem na forma de construir a lógica de consulta.

Etapa 4: Gerar uma API

1. Na página Service Development, passe o mouse sobre o ícone e clique em Create API > Generate API.

   Alternativamente, abra o processo de negócios relevante, clique com o botão direito em API e escolha Create API > Generate API.

2. Na caixa de diálogo Generate API, configure os parâmetros.

   Parâmetro	Descrição
   API Mode	Selecione Wizard Mode ou Code Editor. Se selecionar o modo script, também será necessário escolher um SQL Mode (Basic SQL ou Advanced SQL). Basic SQL: Escreva a lógica de consulta usando sintaxe SQL básica. Advanced SQL: Escreva a lógica de consulta usando sintaxe SQL compatível com tags MyBatis. As tags compatíveis incluem if, choose, when, otherwise, trim, foreach e where.
   API Name	O nome pode conter caracteres chineses, letras, dígitos e sublinhados (_). Deve começar com uma letra ou caractere chinês e ter entre 4 e 50 caracteres.
   APIPath	O caminho do endpoint da API. Trata-se do caminho da solicitação relativo ao host do serviço, como /user. O caminho pode conter letras, dígitos, sublinhados (_) e hifens (-). Deve começar com uma barra (/) e ter até 200 caracteres.
   Protocol	Compatível com HTTP e HTTPS. Para chamar a API via HTTPS, publique-a no API Gateway, vincule um domínio personalizado e faça upload de um certificado SSL no console do API Gateway. Para mais informações, consulte Suporte para HTTPS.
   Request Method	Compatível com GET e POST. Nota Se selecionar GET, a localização do parâmetro de solicitação deve ser QUERY. Se selecionar POST, essa localização pode ser QUERY ou Body.
   Response Type	Apenas JSON é compatível.
   Visible Scope	Work space: A API fica visível para todos os membros do workspace atual. Private: A API fica visível apenas para seu proprietário. Atualmente, não há suporte para autorizar outros usuários.
   Tag	Selecione até cinco tags na lista. Cada tag pode ter até 20 caracteres. Para mais informações, consulte Criar e gerenciar tags de API.
   Description	Insira uma breve descrição para a API. A descrição não pode exceder 2.000 caracteres.
   Location	Selecione um processo de negócios existente para armazenar a API. A estrutura de caminho padrão é "processo de negócios/Nome do Processo de Negócios/API".

3. Clique em Determine para abrir a página de edição da API.

Etapa 5: Configurar a API

Etapa 6: Salvar e enviar

Clique no ícone na barra de ferramentas para salvar a API. O grupo de recursos selecionado entrará em vigor durante os testes.

Apêndice: Do modo assistente para o modo script

Converta uma API do modo assistente para o modo script seguindo estes passos:

1. Na página Service Development, expanda o Workflow > API que contém a API alvo.

2. Clique duas vezes no nome da API para abrir sua página de edição.

3. Na barra de ferramentas, clique no ícone .

4. Na caixa de diálogo Prompt, clique em Determine.

   Aviso

   • A conversão é permitida apenas do modo assistente para o modo script.

   • Esta ação é irreversível.

Apêndice: Exemplos de SQL Avançado (MyBatis)

Estes exemplos demonstram como construir consultas complexas com SQL avançado no modo script. Substitua os nomes das tabelas, campos e condições de consulta pelos seus próprios.

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>

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

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>

Apêndice: Melhor prática — parâmetros opcionais

Em muitos cenários de negócios, alguns parâmetros de solicitação precisam ser opcionais. Isso permite que os chamadores decidam se fornecem ou não um valor para um parâmetro. Se nenhum valor for passado, o parâmetro é excluído das condições de consulta. Esta seção usa a tabela ods_user_info_d como exemplo para mostrar como definir uid como parâmetro obrigatório e gender como parâmetro opcional.

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