Como desenvolver e editar APIs

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Siga as instruções nesta página para usar o Cloud Code ao projetar e editar APIs.

Outros papéis necessários para projetar APIs

Você vai precisar dos papéis listados abaixo para realizar algumas etapas de design e teste de API descritas nesta página.

Tarefa	Papéis necessários
Criar APIs usando o Gemini Code Assist	Gemini para usuário do Google Cloud Consumidor de uso de serviço Consulte Concessão de papéis do IAM em um projeto do Google Cloud para o Gemini Code Assist.
Use o contexto empresarial das suas APIs no hub de APIs ao criar APIs	Leitor do Hub da API Cloud
Registrar as novas APIs no hub de API	Editor ou administrador do Hub da API Cloud
Editar APIs do hub de APIs no Cloud Code	Editor ou administrador do hub de APIs do Cloud
Configurar e gerenciar um servidor simulado remoto para testar APIs	Administrador do Artifact Registry Conta de serviço do Cloud Build Administrador do Cloud Run Administrador do uso do serviço Consulte a referência de papéis básicos e predefinidos do IAM.

Criar APIs com o Gemini Code Assist

Visualização — Gemini Code Assist

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

É possível usar o Cloud Code para projetar APIs da especificação OpenAPI (OAS, na sigla em inglês), versão 3.0 usando o Gemini Code Assist. O Gemini Code Assist pode incluir contexto corporativo para assistência com IA generativa no processo de desenvolvimento da API. O Enterprise Context usa as APIs do hub da API do projeto para fornecer contexto ao gerar novas APIs e está disponível apenas em projetos que usam o hub de APIs.

Consulte Usar o Gemini Code Assist para ver informações sobre as etapas de configuração para usar a funcionalidade nesta seção.

Observação: no momento, o Gemini Code Assist é compatível com o design de APIs que combinam novos objetos com objetos já existentes (se o contexto corporativo estiver ativado). Ele não é compatível com cenários que só reutilizem objetos sem criar novos.

Gerar uma API

Para gerar uma API, siga estas etapas:

1. Clique na varinha mágica na navegação à esquerda para usar o Gemini Code Assist e criar uma nova especificação de API. Use esse método para criar especificações de API em vez do chat do Gemini Code Assist, que não é compatível com todos os recursos e funcionalidades na criação das especificações de API.
   
2. Insira um prompt que descreva a nova API na janela de entrada Criar uma especificação de API.
   1. Se quiser, selecione um modelo de comando entre os ícones mostrados. Um modelo de comando oferece um framework para que ele ajude você a começar.
   2. Insira um comando. Consulte Como escrever prompts de especificação de API eficazes.
      
      
3. O Gemini Code Assist gera um OAS que define a API.
4. Revise a especificação:
   1. Clique em Mostrar código para analisar a especificação no editor de código.
   2. O painel do renderizador de API mostra uma prévia da API que pode ser visualizada pelos desenvolvedores, incluindo a descrição dela e outras documentações.
   3. Se você já tiver APIs de produção no hub de API, esse contexto empresarial será usado para reutilizar objetos de outras APIs para esse OAS e será enumerado no painel OUTPUT:
      
   4. Seu feedback é muito importante. Forneça feedback sobre a especificação gerada clicando no ícone "Gostei" ou "Não gostei" no painel Swagger.
      
   5. Se quiser editar as solicitações de visualização e gerar a especificação novamente, clique nas setas do histórico de solicitações acima das solicitações para alternar entre as solicitações anteriores.
      
5. Teste a especificação. Quando a nova especificação for concluída, você poderá testá-la usando um servidor simulado. Consulte Testar a API usando um servidor simulado.
6. Clique em Salvar para salvar a nova API com um nome que você preferir.
7. Para criar um proxy de API da Apigee com base nessa especificação, clique em Criar proxy de API no menu Mais. O processo de criação cria um pacote de proxy. O novo proxy vai aparecer na lista do menu à esquerda de seus proxies. Consulte o tutorial de criação de proxy de API integrado ao Cloud Code para mais informações sobre como criar proxies no Cloud Code.
   

Como escrever prompts de especificação de API eficazes

A precisão e adequação de uma especificação de API gerada depende muito do comando fornecido ao modelo.

Confira alguns exemplos de comandos bons:

• Crie uma API que permita que os clientes paguem por um pedido usando várias formas de pagamento, como cartões de crédito e débito.
• Aceite ordens de compra para aquisição de grãos de café especiais usando uma API.
• Somos uma pizzaria e queremos criar uma solução on-line personalizada de entrega de pizzas. Crie uma API para aceitar os pedidos de pizza.
• API para empresas de entrega de comida. Os clientes podem pedir uma combinação de pizzas, hambúrgueres ou sanduíches em um único pedido. Cada um desses tipos de alimento tem seu próprio esquema. As pizzas têm recheios e tamanho. Os hambúrgueres têm recheios e tipo de empanada. Os sanduíches têm tipo de pão, carne, vegetais, queijo e instruções personalizadas.

Esses exemplos mostram comandos menos eficazes. Tente evitar solicitações estruturadas como estas:

• Criar uma API para minha loja. O comando contém poucas informações para que o modelo gere uma especificação completa e precisa.
• Criar uma API de reembolso que reutilize o objeto do pedido. Não é necessário especificar quais objetos o Gemini Code Assist precisa reutilizar ao criar novas APIs. O Gemini Code Assist detecta automaticamente os objetos mais adequados para reutilização.

Registrar a API no hub de APIs

Após a revisão e finalização da sua API, registre-a no hub de APIs para disponibilizá-la aos desenvolvedores:

1. Clique em Registrar no hub de APIs.
2. Siga as instruções para registrar a API. Consulte Registrar APIs para informações sobre o registro no hub de APIs e os dados que você precisa fornecer.

Atualizar as APIs do hub de API pelo Cloud Code

É possível salvar uma nova versão das especificações do hub de API ao editá-las no Cloud Code.

Para salvar a especificação como uma nova versão, clique no botão Mais opções... no painel Swagger e clique em Publicar no hub da API. Informe o novo ID da versão da API. A nova versão deve ser exibida na lista de versões da API na lista Hub de API do Cloud Code.

Usar o arquivo de configurações para controlar os comportamentos do Gemini Code Assist

Esta seção explica como usar o arquivo de configurações para gerenciar se o Gemini Code Assist está disponível e como.

Desativar ou ativar o Gemini Code Assist

Depois de configurar a Apigee no Cloud Code (consulte Como configurar a Apigee no Cloud Code), é possível adicionar esta linha ao arquivo de configurações para desativar temporariamente todos os recursos do Gemini Code Assist:

"cloudcode.apigee.gemini.enable": false

Remova a linha ou defina-a como true (o padrão) para reativar o Gemini Code Assist.

Controlar o contexto empresarial na geração de especificações

A geração de OAS pode incluir definições de esquema, metadados e segurança das outras APIs da sua organização. O processo encontra APIs semelhantes usando os nomes e descrições de objetos no catálogo de hub de API que estão no catálogo de hub de API que você tem autorização para acessar. O status da implantação das APIs do hub da API não é considerado.

O contexto empresarial é ativado por padrão.

Você pode:

• Confira o número de modificações incluídas por meio do contexto empresarial, se houver, no painel Swagger:
• Confira as modificações incluídas no painel Saída:

Para desativar o contexto empresarial para a nova geração de especificações, adicione estas linhas no arquivo settings.json após "cloudcode.apigee.gemini.enable": true:

"cloudcode.apigee.gemini.options": {
        "enterpriseContext": {
          "enabled": false,
          "includeMetadata": false,
          "includeSchema": false,
          "includeSecurity": false
        }
    }

Em que:

• enabled especifica se o contexto empresarial é ativado de modo geral. Defina como false para desativar o contexto empresarial.
• includeMetadata controla se o contexto de metadados é incluído. Esta configuração inclui ou exclui metadados de outras APIs no hub da API. includeMetadata só é aplicável quando enabled está definido como true.
• includeSchema controla se o contexto do esquema está incluído. Esta configuração inclui ou exclui informações de esquema de outras APIs no hub da API. includeSchema só é aplicável quando enabled está definido como true.
• includeSecurity controla se o contexto relacionado à segurança é incluído. Esta configuração inclui ou exclui informações de segurança de outras APIs no Hub de APIs. includeSecurity só é aplicável quando enabled está definido como true.

Editar APIs

Se quiser usar o Cloud Code para editar APIs atuais que fazem parte do seu catálogo do hub de APIs, siga estas instruções. As alterações feitas no Cloud Code podem ser salvas novamente no hub da API.

Estas instruções são destinadas a usuários que não usam o complemento Gemini Code Assist para a Apigee. Para informações sobre outras funcionalidades disponíveis com o Gemini Code Assist ao projetar e editar APIs, consulte Criar uma API com o Gemini Code Assist.

Observação: no momento, todas as mudanças feitas na API salvas no hub da API precisam ser salvas como uma nova versão.

Para editar uma especificação de API:

1. Verifique se o projeto selecionado no Cloud Code é aquele com o catálogo do hub de APIs contendo a API que você quer editar.
2. Na navegação à esquerda, expanda a árvore do Hub da API.
3. Selecione na lista a API e a versão que você quer editar.
4. Edite a especificação no painel de edição. Também é possível visualizar as operações da API no painel Swagger.
5. Se quiser, teste a API usando um servidor simulado.
6. Salve as mudanças como uma nova versão usando o botão Mais no painel Swagger e depois Publicar no hub da API. Confirme ou atualize a versão quando solicitado e salve as alterações no hub de API. A nova versão deve ser exibida na lista de versões da API na lista Hub de API do Cloud Code.

Testar a API usando um servidor simulado

É possível testar a API usando um servidor simulado local ou uma simulação remota de servidor baseada no Google Cloud. O servidor simulado local está instalado e disponível por padrão, mas você precisa configurar e gerenciar servidores simulados do Google Cloud.

Usar o servidor simulado local

O servidor simulado local aceita solicitações para essa API e emula respostas. Ele só pode ser usado durante a sessão atual pelo usuário atual. No entanto, ao contrário do servidor de simulação remoto, não requer configuração nem gerenciamento e não gera custos.

Observação: é possível que o servidor simulado local não funcione corretamente ao usar o VS Code Remote Explorer. Às vezes, o servidor simulado local não pode ser iniciado. Nesse caso, elE não estará disponível na lista suspensa.

Para usar o servidor simulado local:

1. Selecione o servidor simulado local (servidor de desenvolvimento) o menu suspenso Servidores.
   
2. Abra um caminho e clique em Testar.
   
3. Preencha todos os parâmetros da solicitação e clique em Executar.
   
4. Também é possível enviar solicitações usando curl em um comando. Use o endereço e a porta do servidor no menu suspenso Servidores.

Usar um servidor simulado remoto

Um servidor simulado remoto permite criar instância de servidor fictício persistente que, ao contrário do servidor simulado local, pode ser compartilhados e usados por outras pessoas na organização para testar a nova API antes que ela seja de produção. Os servidores simulados remotos só podem ser usados com APIs registradas no Hub de APIs.

No momento, servidores simulados remotos podem ser criados no Google Cloud. O Google Os servidores de simulação remotas do Google Cloud não são atualizados automaticamente para nenhuma alteração à API depois de implantar o servidor simulado. Portanto, espere para adicionar o servidor simulado tenham criado a API.

A implantação de um servidor simulado remoto do Google Cloud cria um novo serviço do Cloud Run. Ele cria imagem do contêiner para o servidor simulado usando o Cloud Build e o upload da imagem para o Cloud o Artifact Registry no projeto do Google; você é responsável por qualquer custos e a manutenção resultantes deles após a criação. Você também é será responsável por excluí-las quando não forem mais necessárias. Consulte O que é o Cloud Run?, Como gerenciar serviços e os Documentação do Artifact Registry.

Importante : depois de criar um servidor simulado remoto do Google Cloud você é responsável por quaisquer custos resultantes de seu uso, gerenciá-lo e removê-lo quando for não são mais necessários. Consulte https://cloud.google.com/run/pricing para informações sobre preços, incluindo informações sobre as opções de nível gratuito.

Para implantar um servidor simulado remoto:

1. Selecione Implantar servidor simulado (Google Cloud) no menu Mais.
2. Registre a API quando solicitado, caso ela ainda não esteja registrada no hub da API.
3. Especifique os detalhes do servidor simulado remoto: ID do projeto, Nome do servidor e Região e clique em Criar para criar o servidor simulado remoto.
   Importante: Não crie vários servidores de simulação remota com o mesmo nome, mesmo que a interface do usuário não vão impedir que você faça isso agora.
4. A geração remota do servidor simulado requer vários minutos. Você pode acompanhar o progresso em painel OUTPUT do Google Cloud.
5. Depois que a criação do servidor simulado remoto estiver concluída, o URL do servidor remoto será exibido na Lista de servidores do painel Swagger e o painel OUTPUT.
6. Para usar o servidor simulado, abra um caminho e clique em Testar.
   
   
   Preencha todos os parâmetros da solicitação e clique em Executar.
   
   
   Também é possível enviar solicitações usando um comando curl. Use o endereço e a porta dos Servidores no menu suspenso.

Para compartilhar o acesso ao servidor simulado com outros usuários:

1. Conceda a outros usuários o papel de chamador para o serviço implantado. Consulte Autenticar desenvolvedores.
2. Ao fazer a solicitação ao servidor simulado, os usuários seguem as instruções Teste seu serviço particular.

Siga estas etapas para gerenciar servidores simulados remotos implantados:

1. Acesse o hub de APIs e encontre a API para ver todas as implantações da API, incluindo as servidores simulados remotos.
2. Use o URL do recurso para acessar a implantação e gerenciá-la, interrompendo, excluindo e realizando outras ações no servidor simulado.