Conceber e editar APIs

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Esta página fornece instruções sobre como criar e editar APIs no Apigee no Cloud Code, tirando partido do Gemini Code Assist para acelerar a criação, a edição e a gestão de especificações de APIs.

Antes de começar

Antes de usar a funcionalidade neste guia:

• Certifique-se de que concluiu os passos de configuração para Configurar a gestão de APIs da Apigee no Cloud Code para VS Code, incluindo Usar o Gemini Code Assist com a Apigee.
• Certifique-se de que a sua conta de utilizador tem as funções necessárias indicadas em Funções necessárias para usar o Gemini Code Assist no Apigee para cada tarefa.

Escreva comandos eficazes de especificações da API

Vai pedir ao Gemini Code Assist no Apigee quando criar e editar especificações de APIs. A precisão e a adequação das especificações da API geradas dependem em grande medida dos comandos fornecidos ao modelo.

Para escrever comandos eficazes de criação e edição de especificações da API:

• Com o chat do Gemini Code Assist, use sempre o identificador do Apigee (@Apigee) no início dos seus comandos para criar ou editar especificações de APIs. O identificador do Apigee permite-lhe aceder à ferramenta Apigee, que inclui as funcionalidades de desenvolvimento de especificações de API robustas e com muitas funcionalidades descritas neste guia.
• Use linguagem natural: formule os comandos como se estivesse a dirigir-se a uma pessoa que vai criar a especificação.
• Seja específico: forneça requisitos exatos sempre que possível, como o facto de a sua API de agendamento de consultório dentário ter de incluir vários tipos de consultas e vários locais de consultório dentário.
• Tire partido do contexto empresarial sem especificar nomes de objetos: o Gemini Code Assist deteta e reutiliza de forma inteligente esquemas, metadados e definições de segurança existentes do catálogo do seu hub de APIs. Embora não precise de especificar nomes de objetos exatos, pode sugerir esta capacidade incluindo expressões como Use API Hub ou Leverage Enterprise Context no seu comando.
• Use comandos de seguimento para iterar nas suas APIs: pode usar comandos como "Remover a entidade de localizações desta API" para fazer alterações a uma API.

Seguem-se exemplos de comandos menos e mais eficazes para criar e editar especificações de APIs:

Comando menos eficaz	Explicação do comando	Melhores comandos
"Cria uma API para a minha loja."	Este comando contém poucas informações para o modelo gerar uma especificação completa e precisa.	"Cria uma API para a minha loja para que os clientes verifiquem a disponibilidade dos produtos e adicionem artigos ao carrinho de compras." "Cria uma API que permita aos clientes pagar uma encomenda através de vários métodos de pagamento, como cartões de crédito e cartões de débito."
"Crie uma nova API de reembolso que reutilize o objeto de encomenda."	Não especifique que objetos o Gemini Code Assist deve reutilizar ao criar APIs; O Gemini Code Assist deteta automaticamente os objetos mais adequados para reutilizar.	"Cria uma nova API de reembolso que permite aos clientes pedir um reembolso de uma encomenda anterior."
"Cria uma API para um serviço de entregas."	A API gerada é demasiado genérica.	"Somos um restaurante de pizzas e queremos uma solução de entrega de pizzas personalizada online. Cria uma API para aceitar as encomendas de pizas com o tamanho e os ingredientes da piza." "API para empresas de entrega de refeições. Os clientes podem encomendar uma combinação de pizzas, hambúrgueres ou sanduíches numa única encomenda. Cada um desses tipos de alimentos tem o seu próprio esquema. As pizas têm coberturas e tamanho. Os hambúrgueres têm coberturas e tipo de hambúrguer. Os sanduíches têm tipo de pão, tipo de carne, vegetais, queijo e instruções personalizadas."

Crie APIs com o Gemini Code Assist

Pode usar o Gemini Code Assist no Cloud Code para criar APIs de especificação OpenAPI (OAS), versão 3.0. As APIs concebidas podem incluir o contexto da sua empresa quando geram novas APIs e estão disponíveis apenas com projetos que usam o hub de APIs.

Consulte a secção Antes de começar para ver informações sobre os passos de configuração para usar a funcionalidade descrita nesta secção.

Para gerar uma nova API com o Gemini Code Assist, siga estes passos:

1. Use um destes métodos para aceder ao comando de criação de especificações da API:
   • A partir do Gemini Code Assist: Chat: na janela de chat, introduza o identificador do Apigee, @Apigee e selecione a ferramenta Apigee.
     
   • A partir do Apigee no Cloud Code: clique na varinha mágica na linha do Apigee. Isto carrega o Gemini Code Assist: Chat. Invoque a ferramenta Apigee com @Apigee para iniciar a criação de especificações.
     
2. Selecione Criar especificação da API nas opções da ferramenta Apigee.
3. Conclua o comando com uma descrição da sua nova API. Consulte o artigo Escreva comandos eficazes para especificações de APIs. (Não copie e cole sobre o identificador @Apigee. Em alternativa, conclua o comando escrevendo ou colando o texto após o identificador.)
4. Envie o comando.
5. O Gemini Code Assist gera um OAS que define a API. (Este processo pode demorar até um minuto.) Se o seu hub de APIs incluir outras APIs, a nova OAS pode incorporar objetos e contexto do seu catálogo. O resumo da conversa contextual fornece informações sobre a API gerada e as fontes usadas.
6. Reveja a especificação gerada. A especificação do código YAML e o painel do Swagger para a nova API são apresentados automaticamente nos separadores.
7. Quando a nova especificação estiver concluída, pode testá-la através de um servidor simulado. Consulte o artigo Teste a sua API com um servidor simulado.
8. Para guardar a nova API no catálogo do hub de APIs, consulte o artigo Publique APIs no hub de APIs.
9. Para criar um pacote de proxy de API do Apigee a partir desta especificação, consulte o artigo Guarde APIs como pacotes de proxy de API.

Edite APIs

Pode editar APIs que guardou localmente ou a partir do catálogo do hub de APIs. As alterações que fizer no Cloud Code podem ser guardadas no hub de APIs ou guardadas como um pacote de proxy de API do Apigee.

Edite uma especificação da API a partir do hub de APIs

Para editar uma especificação da API armazenada no catálogo do hub de APIs:

1. Certifique-se de que o projeto que selecionou no Cloud Code é o projeto com o catálogo do hub de APIs que contém a API que quer editar.
2. Na navegação do lado esquerdo, expanda a árvore do API Hub na secção Apigee.
3. Selecione a API e a versão a editar na lista.
4. Veja as operações da API no painel Swagger. Clique em Ver código no painel do Swagger para abrir o ficheiro YAML num separador de edição.

Edite uma especificação da API armazenada localmente

Para editar uma especificação da API armazenada localmente, abra o ficheiro de especificação da API no Cloud Code. Pode atualizar manualmente a especificação ou usar o Gemini Code Assist Chat para iterar na especificação.

Itere nas especificações da API com o chat do Gemini Code Assist

Pode fazer alterações a uma especificação de API existente através do Gemini Code Assist Chat:

1. Carregue o ficheiro de especificação no Cloud Code seguindo as instruções para uma especificação da API a partir do hub de APIs ou um ficheiro de especificação da API local.
2. Certifique-se de que o ficheiro YAML que contém a especificação é o separador atualmente ativo no seu editor.
3. Na janela de chat do Gemini Code Assist, introduza o identificador do Apigee, @Apigee e selecione a ferramenta Apigee.
4. Introduza o comando de atualização das especificações. Consulte o artigo Escreva comandos eficazes de especificações da API para orientação.
5. Opcionalmente, teste a sua API com um servidor simulado.
6. Para guardar a nova API no catálogo do hub de APIs, consulte o artigo Publique APIs no hub de APIs.
7. Para criar um pacote de proxy de API do Apigee a partir desta especificação, consulte o artigo Guarde APIs como pacotes de proxy de API.

Publique APIs no hub de APIs

Se estiver a usar o hub de APIs, pode disponibilizar as suas APIs a outros programadores registando-as no hub de APIs:

1. No painel do Swagger para uma especificação da API nova ou editada, clique em Publish to API hub.
2. No formulário, forneça metadados para a API para melhorar a respetiva capacidade de deteção e organização das APIs no catálogo do seu hub de APIs. A maioria dos campos é preenchida automaticamente a partir da especificação da API, mas pode alterar os valores. Consulte o artigo Registe uma API para informações sobre o registo no hub de APIs e as informações que tem de fornecer.
   • Nome a apresentar da API (obrigatório): um nome da API visível para outros programadores.
   • Descrição da API (opcional): uma descrição da API para referência interna/do programador.
   • Nome do proprietário da API (opcional): o nome do proprietário da API.
   • Email do proprietário da API (opcional): o endereço de email do proprietário.
   • Versão da API (obrigatório): a versão da API.
   • Fase do ciclo de vida (opcional): selecione uma fase na lista.
3. Clique em Publicar para publicar a API no hub de APIs.
4. Após um breve atraso, as alterações devem estar visíveis na árvore do API Hub na secção do Apigee do Cloud Code.

Teste APIs com um servidor simulado

Pode testar a sua API através de um servidor simulado local ou de um servidor simulado remoto baseado em Google Cloud. O servidor de simulação local é instalado e está disponível por predefinição, enquanto tem de configurar e gerir Google Cloud servidores de simulação.

Use o servidor de teste local

O servidor de simulação local aceita pedidos a esta API e emula respostas. Só é utilizável durante a sessão atual pelo utilizador atual. No entanto, ao contrário do servidor de simulação remoto, não requer configuração nem gestão e não incorre em custos.

Além disso, os servidores de simulação locais:

• Não funcionam quando usa o Cloud Shell Editor ou as estações de trabalho na nuvem.
• Pode não funcionar corretamente quando usar o VS Code Remote Explorer.

Para usar o servidor de simulação local:

1. Selecione o servidor de simulação local no menu pendente Servidores (se ainda não estiver selecionado):
   
2. Abra um caminho no painel do Swagger e clique em Experimentar.
   
3. Preencha os parâmetros do pedido e clique em Executar.
   

Use um servidor de simulação remoto

Um servidor simulado remoto oferece a capacidade de criar uma instância de servidor simulado persistente que, ao contrário do servidor simulado local, pode ser partilhada e usada por outras pessoas na sua organização para testar a nova API. Os servidores de simulação remotos só podem ser usados com APIs registadas no hub de APIs.

Os servidores de simulação remotos não são atualizados automaticamente para quaisquer alterações que faça à API depois de implementar o servidor de simulação. Por isso, aguarde até ter criado totalmente a API para adicionar o servidor de simulação.

A implementação de um Google Cloud servidor de simulação remoto cria um novo serviço do Cloud Run. Cria uma imagem de contentor para o servidor simulado através do Cloud Build e carrega a imagem de contentor para o Cloud Artifact Registry no seu projeto Google. Consulte o artigo O que é o Cloud Run?, Gerir serviços e a documentação do Artifact Registry.

Pode usar a conta de serviço predefinida ou fornecer uma conta de serviço mais restrita para implementar a aplicação do Cloud Run. Consulte o artigo Faça a gestão das APIs Cloud e das bibliotecas cliente do Google Cloud no Cloud Code para VS Code para mais informações.

Importante: é responsável por todos os custos e pela manutenção resultantes no servidor de simulação remoto após a criação. Também é responsável por eliminá-lo quando já não for necessário ou estiver em utilização. Consulte os preços do Cloud Run para ver informações de preços, incluindo informações sobre opções de nível gratuito.

Para implementar um servidor de simulação remoto:

1. Selecione Implementar servidor simulado no painel do Swagger.
2. Se a sua API ainda não estiver registada no hub de APIs, registe-a quando lhe for pedido.
3. Especifique os detalhes do servidor de simulação remoto: Nome do servidor, Servidor seguro, Conta de serviço (deixe em branco para usar a conta de serviço predefinida) e se quer adicionar o URL do servidor à especificação da API. Clique em Criar para criar o servidor de simulação remoto.
   Importante: Não crie vários servidores de simulação remotos com o mesmo nome, embora a interface do utilizador não o impeça de o fazer neste momento.
4. A geração de um servidor simulado remoto requer vários minutos. Pode ver o progresso no painel OUTPUT do Cloud Code e através da janela de notificação na parte inferior direita do VS Code.
5. Quando o processo de criação do servidor de simulação remoto estiver concluído, verá o URL do servidor remoto na lista de servidores do painel do Swagger e no painel OUTPUT.
6. Para usar o servidor simulado, abra um caminho e clique em Experimentar.
   
   
   Preencha todos os parâmetros do pedido e clique em Executar.
   
   
   Também pode enviar pedidos através do curl a partir de um comando. Use o endereço do servidor e a porta do menu pendente Servidores.

Para partilhar o acesso ao servidor simulado com outros utilizadores:

1. Atribua a outros utilizadores a função de invocador para o serviço implementado. Consulte Autentique programadores.
2. Ao fazer o pedido ao servidor simulado, os utilizadores seguem as instruções em Teste o seu serviço privado.

Para gerir servidores simulados remotos implementados:

1. Aceda ao Apigee API hub.
2. Encontre a API para ver todas as implementações da API, que incluem todos os servidores de simulação remotos.
3. Use o URL do recurso para aceder à implementação e geri-la parando, eliminando e realizando outras ações no servidor simulado.

Guarde APIs como pacotes de proxy de API

Pode guardar a sua API como um pacote de proxy de API do Apigee para poder trabalhar nela no seu ambiente de desenvolvimento local do Apigee. Para informações sobre como trabalhar com proxies de API no Cloud Code, consulte o artigo Desenvolva proxies de API.

1. Clique em Criar pacote de proxy de API no painel do Swagger.
2. No campo de comando, atribua um nome ao proxy de API e continue.
3. O proxy de API aparece no menu do lado esquerdo do Apigee no seu espaço de trabalho local, em apiproxies.

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

A geração de OAS pode incluir esquemas, metadados e definições de segurança de outras APIs da sua organização. O processo encontra APIs semelhantes através dos nomes e das descrições dos objetos. O estado de implementação das APIs do hub de APIs não é considerado.

O contexto empresarial está ativado por predefinição.

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

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

Onde:

• enabled especifica se o contexto empresarial está ativado globalmente. Defina como false para desativar o contexto empresarial.
• includeMetadata controla se o contexto dos metadados está incluído. Esta definição inclui ou exclui metadados de outras APIs no hub de APIs. includeMetadata só é aplicável quando enabled está definido como true.
• includeSchema controla se o contexto do esquema está incluído. Esta definição inclui ou exclui informações de esquemas de outras APIs no hub de APIs. includeSchema só é aplicável quando enabled está definido como true.
• includeSecurity controla se o contexto relacionado com a segurança está incluído. Esta definiçã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.