Documentação do Oracle Cloud Infrastructure

Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API

Descubra como implantar uma API em um gateway de API criando uma implantação de API com o serviço de Gateway de API.

Tendo criado um gateway de API, você implanta uma API no gateway de API criando uma implantação de API. Quando você cria uma implantação de API, inclui uma especificação de implantação de API que define a API. O serviço API Gateway inspeciona a especificação de implantação de API para confirmar que é válida.

Você pode usar um gateway de API único como front-end para diversos serviços de back-end:

  • Criando uma implantação de API única no gateway de API, com uma especificação de implantação de API que define vários serviços de back-end.
  • Criando várias implantações de API no mesmo gateway de API, cada uma com uma especificação de implantação de API que define um (ou mais) serviços de back-end.

Usando a Console para Criar uma Implantação de API do Início

Para usar a Console na criação de uma implantação de API, informe a especificação de implantação de API em caixas de diálogo na Console conforme você for prosseguindo:

  1. Na página da lista Gateways, selecione o gateway de API no qual você deseja implantar a API. Se precisar de ajuda para localizar a página da lista ou o gateway de API, consulte Listando Gateways de API.
  2. Na página Detalhes do Gateway, selecione Implantações na lista Recursos e, em seguida, selecione Criar Implantação.

  3. Selecione Totalmente Novo e, na seção Informações Básicas, especifique:

    • Nome: O nome da nova implantação de API. Evite digitar informações confidenciais.

    • Prefixo do Caminho: Um caminho no qual serão implantadas todas as rotas contidas na especificação de implantação da API. Por exemplo:

      • /v1
      • /v2
      • /test/20191122

      Observe que o prefixo do caminho de implantação que você especificar:

      • deve ser precedido por uma barra ( / ) e pode ser apenas uma barra
      • pode conter várias barras (desde que elas não sejam adjacentes), mas não deve terminar com uma barra
      • pode incluir caracteres alfanuméricos maiúsculos e minúsculos
      • pode incluir os caracteres especiais $ - _ . + ! * ' ( ) , % ; : @ & =
      • não pode incluir parâmetros e curingas

      Observe também que, se uma implantação de API tiver uma única barra como prefixo do caminho de implantação, essa será a única implantação de API permitida em um determinado gateway de API. Você não poderá criar uma implantação de API com uma única barra como prefixo do caminho de implantação se já houver outra implantação de API no mesmo gateway de API.

    • Compartimento: O compartimento no qual será criada a nova implantação de API.

  4. (Opcional) Na seção Políticas de Solicitação de API, especifique opcionalmente os detalhes da política de solicitação para fornecer suporte para:

  5. (Opcional) Na seção Políticas de Registro em Log da API, opcionalmente, especifique um nível de log de execução para registrar informações sobre processamento dentro do gateway da API. Consulte Adicionando Registro em Log a Implantações de API.

  6. (Opcional) Selecione Mostrar Opções Avançadas e, opcionalmente, especifique:

    • Tags: 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 as tags posteriormente.
  7. Selecione Próximo para exibir a página Autenticação e informe os detalhes de uma política de solicitação de autenticação:

    Para obter mais informações, consulte Adicionando Autenticação e Autorização a Implantações de API.

  8. Selecione Próximo para informar detalhes das rotas na implantação de API.

  9. Na seção Rota 1, especifique a primeira rota na implantação de API que mapeia um caminho e um ou mais métodos para um serviço de back-end:

    • Caminho: Um caminho para chamadas de API usando os métodos listados para o serviço de back-end. Observe que o caminho da rota que você especificar:

      • é relativo ao prefixo do caminho de implantação
      • deve ser precedido por uma barra ( / ) e pode ser apenas uma barra
      • pode conter várias barras (desde que elas não sejam adjacentes) e pode terminar com uma barra
      • pode incluir caracteres alfanuméricos maiúsculos e minúsculos
      • pode incluir os caracteres especiais $ - _ . + ! * ' ( ) , % ; : @ & =
      • pode incluir parâmetros e curingas (consulte Adicionando Parâmetros de Caminho e Curingas a Caminhos de Rota)
    • Métodos: Um ou mais métodos aceitos pelo serviço de back-end, separados por vírgulas. Por exemplo, GET, PUT.

    • Adicionar um único backend ou Adicionar vários backends: Se todas as solicitações devem ser roteadas para o mesmo back-end ou para rotear solicitações para diferentes back-ends de acordo com a variável de contexto e as regras informadas.

      Essas instruções pressupõem que você deseja usar um único back-end; portanto, selecione Adicionar um único backend. Como alternativa, se você quiser usar back-ends diferentes, selecione Adicionar vários back-ends e siga as instruções em Usando a Console para Adicionar Seleção de Back-End Dinâmico a uma Especificação de Implantação de API.

    • Tipo de Backend: O tipo do serviço de back-end, como:
  10. (Opcional) Selecione Outra Rota para inserir detalhes de rotas adicionais.
  11. Selecione Próximo para revisar os detalhes informados para a nova implantação de API.

  12. Selecione Criar para criar a nova implantação de API.

    Observe que pode levar alguns minutos para criar a nova implantação de API. Enquanto está sendo criada, a implantação de API é mostrada com o estado Criando na página Detalhes do Gateway. Quando ela tiver sido criada com sucesso, a nova implantação da API será mostrada com um estado de Ativa.

    Observe também que, em vez de criar a nova implantação de API imediatamente, você pode criá-la posteriormente usando o Resource Manager e o Terraform, selecionando 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.

  13. Se você tiver aguardado mais do que alguns minutos para que a implantação da API seja mostrada com um estado Ativo (ou se a operação de criação de implantação da API tiver falhado):

    1. Selecione o nome da implantação da API e selecione Solicitações de Serviço para ter uma visão geral da operação de criação de implantação da API.
    2. Selecione a operação Criar Implantação 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 criação da implantaçã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 Solucionando Problemas do Serviço API Gateway.
  14. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Usando a Console para Criar uma Implantação de API com Base em um Arquivo JSON

Para usar a Console para criar uma implantação de API, fazendo upload da especificação de implantação de API com base em um arquivo JSON:

  1. Na página da lista Gateways, selecione o gateway de API no qual você deseja implantar a API. Se precisar de ajuda para localizar a página da lista ou o gateway de API, consulte Listando Gateways de API.
  2. Na página Detalhes do Gateway, selecione Implantações na lista Recursos e, em seguida, selecione Criar Implantação.
  3. Selecione Carregar uma API existente.

  4. Na seção Informações de Upload, especifique:

    • Nome: O nome da nova implantação de API. Evite digitar informações confidenciais.

    • Prefixo do Caminho: Um caminho no qual serão implantadas todas as rotas contidas na especificação de implantação da API. Por exemplo:

      • /v1
      • /v2
      • /test/20191122

      Observe que o prefixo do caminho de implantação que você especificar:

      • deve ser precedido por uma barra ( / ) e pode ser apenas uma barra
      • pode conter várias barras (desde que elas não sejam adjacentes), mas não deve terminar com uma barra
      • pode incluir caracteres alfanuméricos maiúsculos e minúsculos
      • pode incluir os caracteres especiais $ - _ . + ! * ' ( ) , % ; : @ & =
      • não pode incluir parâmetros e curingas
    • Compartimento: O compartimento no qual será criada a nova implantação de API.
    • Especificação: O arquivo JSON que contém a especificação de implantação de API, seja arrastando e soltando o arquivo ou selecionando selecionar um. Consulte Criando uma Especificação de Implantação de API.

    Observe também que, se uma implantação de API tiver uma única barra como prefixo do caminho de implantação, essa será a única implantação de API permitida em um determinado gateway de API. Você não poderá criar uma implantação de API com uma única barra como prefixo do caminho de implantação se já houver outra implantação de API no mesmo gateway de API.

  5. (Opcional) Selecione Mostrar Opções Avançadas e, opcionalmente, especifique:

    • Tags: 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.
  6. Selecione Próximo para revisar os detalhes informados para a nova implantação de API.

  7. Selecione Criar para criar a nova implantação de API.

    Observe que pode levar alguns minutos para criar a nova implantação de API. Enquanto está sendo criada, a implantação de API é mostrada com o estado Criando na página Detalhes do Gateway. Quando ela tiver sido criada com sucesso, a nova implantação da API será mostrada com um estado de Ativa.

    Observe também que, em vez de criar a nova implantação de API imediatamente, você pode criá-la posteriormente usando o Resource Manager e o Terraform, selecionando 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.

  8. Se você tiver aguardado mais do que alguns minutos para que a implantação da API seja mostrada com um estado Ativo (ou se a operação de criação de implantação da API tiver falhado):

    1. Selecione o nome da implantação da API e selecione Solicitações de Serviço para ter uma visão geral da operação de criação de implantação da API.
    2. Selecione a operação Criar Implantação 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 criação da implantaçã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 Solucionando Problemas do Serviço API Gateway.
  9. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Usando a Console para Criar uma Implantação de API com Base em um Recurso da API

Você pode criar uma implantação de API com base em um recurso de API existente, usando a descrição da API do recurso de API. Nesse caso, a descrição da API se baseia em um arquivo de descrição da API submetido a upload para o recurso da API (consulte Criando um Recurso da API com uma Descrição da API). O arquivo de descrição da API fornece alguns valores iniciais para a especificação de implantação da API, que você pode modificar e estender ao criar a implantação da API. Em particular, uma rota padrão é criada para cada caminho e método associado na descrição da API.

Para usar a Console a fim de criar uma implantação de API com base em um recurso de API existente, usando uma especificação de implantação de API derivada de um arquivo de descrição de API:

  1. Na página de lista APIs, selecione o nome do recurso de API que você deseja implantar. Se precisar de ajuda para localizar a página da lista, consulte Listando Recursos da API.
  2. (Opcional) Na página Detalhes da API, selecione Especificação de Implantação de API na lista Recursos para confirmar se uma especificação de implantação de API válida foi criada para o recurso de API com base em um arquivo de descrição de API submetido a upload. Se nenhuma especificação de implantação de API estiver disponível, consulte Criando um Recurso de API com uma Descrição de API
  3. Na página Detalhes da API, selecione Implantar Gateway de API para usar as caixas de diálogo Console para criar uma implantação de API.

    Alguns dos valores iniciais das propriedades de especificação da implantação da API mostradas nas caixas de diálogo Console são derivados do arquivo de descrição da API.

    A seção Informações da API mostra detalhes sobre o recurso da API com base no qual a implantação da API será criada.

  4. Na seção Gateway, selecione o gateway da API no qual criar a implantação da API. Se ainda não existir um gateway de API adequado, selecione Criar Gateway para criar um (consulte Criando um Gateway de API).

  5. Na seção Informações Básicas, especifique:

    • Nome: O nome da nova implantação de API. Evite digitar informações confidenciais.

    • Prefixo do Caminho: Um caminho no qual serão implantadas todas as rotas contidas na especificação de implantação da API.

      Por exemplo:

      • /v1
      • /v2
      • /test/20191122

      Observe que o prefixo do caminho de implantação que você especificar:

      • deve ser precedido por uma barra ( / ) e pode ser apenas uma barra
      • pode conter várias barras (desde que elas não sejam adjacentes), mas não deve terminar com uma barra
      • pode incluir caracteres alfanuméricos maiúsculos e minúsculos
      • pode incluir os caracteres especiais $ - _ . + ! * ' ( ) , % ; : @ & =
      • não pode incluir parâmetros e curingas

      Observe também que, se uma implantação de API tiver uma única barra como prefixo do caminho de implantação, essa será a única implantação de API permitida em um determinado gateway de API. Você não poderá criar uma implantação de API com uma única barra como prefixo do caminho de implantação se já houver outra implantação de API no mesmo gateway de API.

    • Compartimento: O compartimento no qual será criada a nova implantação de API.

  6. (Opcional) Na seção Políticas de Solicitação de API, especifique opcionalmente os detalhes da política de solicitação para fornecer suporte para:

  7. (Opcional) Na seção Políticas de Registro em Log da API, opcionalmente, especifique um nível de log de execução para registrar informações sobre processamento dentro do gateway da API. Consulte Adicionando Registro em Log a Implantações de API.

  8. (Opcional) Selecione Mostrar Opções Avançadas e, opcionalmente, especifique:

    • Tags: 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 as tags posteriormente.

  9. Selecione Próximo para analisar e informar detalhes das rotas na implantação de API.

    Por padrão, uma rota é criada para cada caminho e método associado que está presente na descrição da API. Inicialmente, cada uma dessas rotas padrão é criada com um back-end de resposta padrão. O código de status HTTP, o conteúdo no corpo do conteúdo do corpo da resposta e o cabeçalho são obtidos dos detalhes na descrição da API. Se a descrição da API não incluir informações de resposta para um caminho específico e um método associado, um back-end de resposta padrão será criado para essa rota com 501 como código de status HTTP.

  10. Revise cada rota padrão, por sua vez, modificando sua configuração, se necessário, para atender aos seus requisitos, e adicionando políticas de solicitação, resposta e registro em log:

  11. (Opcional) Selecione Outra Rota para informar detalhes de mais rotas, além das criadas por padrão com base na descrição da API.
  12. Selecione Próximo para revisar os detalhes informados para a nova implantação de API.

  13. Selecione Criar para criar a nova implantação de API.

    Observe que pode levar alguns minutos para criar a nova implantação de API. Enquanto está sendo criada, a implantação de API é mostrada com o estado Criando na página Detalhes do Gateway. Quando ela tiver sido criada com sucesso, a nova implantação da API será mostrada com um estado de Ativa.

  14. Se você tiver aguardado mais do que alguns minutos para que a implantação da API seja mostrada com um estado Ativo (ou se a operação de criação de implantação da API tiver falhado):

    1. Selecione o nome da implantação da API e selecione Solicitações de Serviço para ter uma visão geral da operação de criação de implantação da API.
    2. Selecione a operação Criar Implantação 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 criação da implantaçã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 Solucionando Problemas do Serviço API Gateway.
  15. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Usando a CLI

Para criar uma nova implantação de API usando a CLI:

  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 deployment create para criar a implantação:

    oci api-gateway deployment create --compartment-id <compartment-ocid> --display-name <api-name> --gateway-id <gateway-ocid> --path-prefix "/<deployment-path-prefix>" --specification file:///<filename>

    em que:

    • <compartment-ocid> é o OCID do compartimento no qual será criada a nova implantação de API.
    • <api-name> é o nome da nova implantação de API. Evite digitar informações confidenciais.
    • <gateway-ocid> é o OCID do gateway existente no qual a API será implantada. Para descobrir o OCID do gateway de API, consulte Lista de Gateways de API.

    • /<deployment-path-prefix> é um caminho no qual serão implantadas todas as rotas contidas na especificação de implantação de API.

      Observe que o prefixo do caminho de implantação que você especificar:

      • deve ser precedido por uma barra ( /) no arquivo JSON e pode ser apenas uma barra
      • pode conter várias barras (desde que elas não sejam adjacentes), mas não deve terminar com uma barra
      • pode incluir caracteres alfanuméricos maiúsculos e minúsculos
      • pode incluir os caracteres especiais $ - _ . + ! * ' ( ) , % ; : @ & =
      • não pode incluir parâmetros e curingas

      Observe também que, se uma implantação de API tiver uma única barra como prefixo do caminho de implantação, essa será a única implantação de API permitida em um determinado gateway de API. Você não poderá criar uma implantação de API com uma única barra como prefixo do caminho de implantação se já houver outra implantação de API no mesmo gateway de API.

    • <filename> é a especificação de implantação de API, incluindo um caminho, um ou mais métodos e uma definição de back-end. Consulte Criando uma Especificação de Implantação de API.

    Por exemplo:

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json

    A resposta ao comando inclui:

    • O OCID da implantação de API.

    • O nome do host em que a implantação de API foi criada, como um nome de domínio no formato <gateway-identifier>.apigateway.<region-identifier>.oci.customer-oci.com, em que:

      • <gateway-identifier> é a string de caracteres que identifica o gateway de API. Por exemplo, lak...sjd (abreviado para fins de legibilidade).
      • <region-identifier> é o identificador da região na qual a implantação de API foi criada. Consulte Disponibilidade por Região.

      Por exemplo, lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com.

      O nome do host será o nome do domínio a ser usado ao chamar uma API implantada no gateway de API.

    • O estado do ciclo de vida (por exemplo, ACTIVE, FAILED).
    • O id da solicitação de serviço para criar a implantação de API (detalhes das solicitações de serviço estão 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 a implantação de API esteja ativa (ou que a solicitação tenha falhado), inclua um ou ambos os parâmetros a seguir:

    • --wait-for-state ACTIVE
    • --wait-for-state FAILED

    Por exemplo:

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json --wait-for-state ACTIVE

    Observe que você não pode usar a implantação da API até que a solicitação de serviço a tenha criado com sucesso e a implantação da API esteja ativa.

  3. (Opcional) Para ver o status da implantação da API, informe:

    oci api-gateway deployment get --deployment-id <deployment-ocid>

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

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

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

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

  6. (Opcional) Se a solicitação de trabalho que está criando a implantação 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.