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

Pré-requisitos

• Você já configurou uma fonte de dados na página Workspace Management > Data source management. Para mais detalhes, consulte {{XREF_1}}.

• O serviço de dados exige um grupo de recursos. Em ambientes de produção, recomendamos o uso de um grupo de recursos serverless. Para mais detalhes, consulte {{XREF_2}}.

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 seguintes tarefas 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 é um conjunto de APIs para um recurso ou cenário específico, funcionando 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

Os processos de negócios organizam o desenvolvimento de APIs por domínio de negócio. Cada processo deve estar vinculado a um grupo de APIs, sendo obrigatório criar um 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 dentro do 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 a criação do processo de negócios, você poderá visualizá-lo na lista Workflow.

Etapa 3: Escolher o modo da API

O DataService Studio oferece suporte ao modo assistente e ao modo script. Ambos compartilham o mesmo processo básico de configuração, mas diferem na forma de construção da 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 optar pelo modo script, também será necessário selecionar 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 com suporte a tags MyBatis. As tags suportadas 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	Suporta HTTP e HTTPS. Para chamar a API via HTTPS, é necessário publicá-la no API Gateway, vincular um domínio personalizado e fazer upload de um certificado SSL no console do API Gateway. Para mais informações, consulte {{XREF_4}}.
   Request Method	Suporta GET e POST. Nota Se selecionar GET, a posição do parâmetro de solicitação deve ser QUERY. Se selecionar POST, essa posição pode ser QUERY ou Body.
   Response Type	Somente JSON é suportado.
   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 {{XREF_5}}.
   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)

Os exemplos abaixo demonstram padrões comuns de consulta usando SQL avançado no modo script. Substitua os nomes das tabelas, campos e condições 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

Alguns parâmetros de solicitação podem precisar ser opcionais — 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 para demonstrar a definição de uid como obrigatório e gender como opcional.

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