Documentação do Oracle Cloud Infrastructure

Criando um Recurso da API com uma Descrição da API

Descubra como criar um recurso de API com o serviço de Gateway de API que você pode usar para implantar uma API em um gateway de API.

Ao usar o serviço API Gateway, você tem a opção de criar um recurso de API. Você pode usar o recurso de API para implantar uma API em um gateway de API. O recurso da API tem uma descrição da API que descreve a API.

Se você usar um recurso de API para implantar uma API em um gateway de API, sua descrição de API preencherá previamente algumas das propriedades da especificação de implantação de API.

Opcionalmente, você pode importar a descrição da API de um arquivo (às vezes chamado de "especificação da API" ou "espec. da API") escrito em um idioma suportado. No momento há suporte para o OpenAPI Specification versão 2.0 (anteriormente Swagger Specification 2.0) e a versão 3.0.

Observe que a criação de um recurso de API no serviço API Gateway é opcional. Você pode implantar uma API em um gateway de API sem criar um recurso de API no serviço API Gateway. Observe também que você pode criar um recurso de API que não tenha uma descrição de API inicialmente e, em seguida, adicionar uma descrição de API posteriormente.

    1. Na página da lista APIs, selecione Criar API. Se precisar de ajuda para localizar a página da lista, consulte Listando Recursos da API.

    2. Especifique os seguintes valores para o recurso de API:

      • Nome: O nome do recurso de API. Evite digitar informações confidenciais.
      • Compartimento: O compartimento no qual criar o recurso de API.
      • Fazer Upload do arquivo de descrição da API: (Opcional) Um arquivo que contém a descrição da API (em um idioma suportado) para fazer upload e do qual criar a descrição da API. O arquivo pode ter até 1 MB de tamanho. O arquivo é submetido a parsing para confirmar se está em um idioma suportado e formatado corretamente. No momento, há suporte para os arquivos do OpenAPI Specification versão 2.0 (anteriormente Swagger Specification 2.0) e versão 3.0.
      • Mostrar opções avançadas: Selecione essa opção para aplicar tags ao recurso. Se você tiver permissões para criar um recurso, também terá permissões para aplicar tags de formato livre a esse recurso. Para aplicar uma tag definida, você deve ter permissões para usar o namespace da tag. Para obter mais informações sobre tags, consulte Tags de Recursos. Se você não tiver certeza se deseja aplicar tags, ignore essa opção ou pergunte a um administrador. Você pode aplicar tags posteriormente.

    3. Selecione Criar API para criar o recurso de API.

      Se você tiver feito upload de um arquivo de descrição de API, uma descrição de API será criada e validada. Pode levar alguns minutos para validar a descrição da API. Enquanto ele está sendo validado, a descrição da API é mostrada com um estado de Validação na página Validações. Quando a descrição da API for validada com sucesso, ocorrerão as seguintes ações:

      • A página Validações mostra a validação bem-sucedida.
      • A página de descrição da API mostra a descrição da API criada com base no arquivo de descrição da API.
      • A página Especificação de Implantação de API mostra qualquer informação adicional sobre a especificação de implantação de API padrão criada com base na descrição da API.

      Observe que, em vez de criar o recurso de API imediatamente, você pode criá-lo posteriormente usando o Resource Manager e o Terraform. Selecione Salvar como pilha para salvar a definição de recurso como uma configuração do Terraform. Para obter mais informações sobre como salvar pilhas de definições de recursos, consulte Criando uma Pilha de uma Página de Criação de Recurso.

    4. Se você tiver aguardado mais de alguns minutos para que a descrição da API seja mostrada como Válida (ou se a operação de validação da descrição da API tiver falhado), siga estas etapas:

      1. Selecione Solicitações de serviço para ver uma visão geral da operação de validação da descrição da API.
      2. Selecione a operação Validar API para ver mais informações sobre a operação (incluindo mensagens de erro, mensagens de log e o status de recursos associados).
      3. Se a operação de validação da descrição da API tiver falhado e você não puder diagnosticar a causa do problema com base nas informações da solicitação de serviço, consulte Solução de Problemas do Serviço API Gateway.

    5. Se você não fez upload de um arquivo de descrição de API quando criou o recurso de API pela primeira vez, ou se quiser fazer upload subsequentemente de outro arquivo de descrição de API, siga estas etapas:

      1. Na página APIs, selecione Editar no menu Ações Menu Ações do recurso da API.
      2. Forneça detalhes do arquivo de descrição da API com base no qual a descrição da API será criada.

    Depois de criar com sucesso um recurso de API com uma descrição de API, você poderá implantá-lo em um gateway de API. Consulte Usando a Console para Criar uma Implantação de API de um Recurso da API.

  • Para criar um recurso de API usando a CLI, siga estas etapas:

    1. Configure seu ambiente de cliente para usar a CLI ( Configurando Seu Ambiente de Cliente para usar a CLI para o Desenvolvimento de Gateway de API).
    2. Abra um prompt de comando e execute oci api-gateway api create para criar o recurso de API:
      oci api-gateway api create --display-name "<api-name>" --compartment-id <compartment-ocid> --content "<api-description>"

      em que:

      • <api-name> é o nome do novo recurso de API. Evite digitar informações confidenciais.
      • <compartment-ocid> é o OCID do compartimento ao qual pertencerá o novo recurso de API.
      • <api-description> é opcionalmente uma descrição da API (em um idioma suportado). O valor especificado para <api-description> pode ser:
        • Toda a descrição da API, entre aspas duplas. Dentro da descrição, cada aspa dupla deve ter escape com um caractere de barra invertida (\). Por exemplo (e abreviado para legibilidade), --content "swagger:\"2.0\",title:\"Sample API\",..."
        • O nome e a localização de um arquivo de descrição de API, entre aspas duplas e no formato "$(< <path>/<filename>.yaml)". Por exemplo, --content "$(< /users/jdoe/api.yaml)"
        A descrição é submetida a parsing para confirmar se está em um idioma suportado e formatada corretamente. No momento, há suporte para os arquivos do OpenAPI Specification versão 2.0 (anteriormente Swagger Specification 2.0) e versão 3.0.

      Por exemplo:

      oci api-gateway api create --display-name "Hello World API Resource" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --content "swagger:\"2.0\",title:\"Sample API\",..."

      A resposta ao comando inclui:

      • O OCID do recurso de API.
      • O estado do ciclo de vida (por exemplo, SUCCEEDED, FAILED).
      • O id da solicitação de serviço para criar o recurso de API (detalhes das solicitações de serviço ficam disponíveis por sete dias após a conclusão, o cancelamento ou a falha).

      Se quiser que o comando aguarde o retorno de controle até que o recurso de API tenha sido criado (ou a solicitação tenha falhado), inclua um ou ambos os seguintes parâmetros:

      • --wait-for-state SUCCEEDED
      • --wait-for-state FAILED

      Por exemplo:

      oci api-gateway api create --display-name "Hello World API Resource" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --content "swagger:\"2.0\",title:\"Sample API\",..." --wait-for-state SUCCEEDED

      Observe que você só poderá usar o recurso de API quanto a solicitação de serviço o tiver criado com sucesso.

    3. (Opcional) Para ver o status da solicitação de serviço que está criando o recurso de API, informe:

      oci api-gateway work-request get --work-request-id <work-request-ocid>

    4. (Opcional) Para exibir os logs da solicitação de serviço que está criando o recurso de API, informe:

      oci api-gateway work-request-log list --work-request-id <work-request-ocid>

    5. (Opcional) Se a solicitação de serviço que está criando o recurso de API falhar e você quiser revisar os logs de erro, informe:

      oci api-gateway work-request-error --work-request-id <work-request-ocid>

    Para obter mais informações sobre o uso da CLI, consulte Interface de Linha de Comando (CLI). Para obter uma lista completa de flags e opções disponíveis para comandos da CLI, consulte a Ajuda da CLI.

  • Execute a operação CreateAPI para criar um recurso de API.