Funções: Validar uma Chave de API com o API Gateway

• Uma conta do Oracle Cloud Infrastructure paga. Consulte Cadastrando-se no Oracle Cloud Infrastructure.
• Sua conta do OCI configurada para suportar o desenvolvimento do Oracle Functions. Consulte Início Rápido do Oracle Functions no Cloud Shell.
• Conclusão de um dos dois tutoriais de introdução do Oracle Functions.
  • Funções: Conceitos Básicos do uso do Cloud Shell
  • Funções: Conceitos Básicos do uso da CLI
• A conclusão de um dos dois tutoriais resulta em:
  • O Oracle Functions está instalado e configurado para criar aplicativos e implantar funções.
  • O Oracle Registry é configurado para armazenar imagens de funções.
  • O Docker é conectado ao Oracle Registry.
  • A VCN necessária e os recursos obrigatórios necessários para o Oracle Functions.
  • Um par de chaves de API e um token de autenticação.

CLI da Oracle

• Python 3.6+ e pip3.
• Mecanismo Docker: um computador Linux ou uma VM Linux. Consulte Requisitos do mecanismo Docker para ver as versões e distribuições suportadas.
• Docker Desktop: Disponível para MacOS ou Windows 10.
  • Windows 10: atualização 2004 do Windows 10 com WSL 2 e Ubuntu ou outra distribuição instalada.
    • Consulte Windows Subsystem for Linux Installation Guide for Windows 10.
    • Instale o Docker Desktop para Windows 10.
    Observação
    
    O Docker inclui suporte especial ao Linux para WSL 2 no Windows 10 atualização 2004.
  • MacOS: Consulte Install Docker Desktop for MacOS.

Oracle Cloud Shell

• Se você usar o Cloud Shell, a lista anterior de software já estará instalada.

Para criar um compartimento, consulte Criar um compartimento. Depois que seu compartimento for criado, salve o OCID e o nome do compartimento.

Para obter o OCID do compartimento de um compartimento existente:

1. Abra o menu de navegação e clique em Identidade e Segurança. Em Identidade, clique em Compartimentos.
2. Selecione seu compartimento.
3. Clique no link Copiar do campo OCID.

Salve o OCID e o nome do compartimento.

Verifique se você tem as seguintes informações anotadas para o tutorial.

• Nome do Compartimento: <your-compartment-name>

  Exemplo: my-compartment

• ID do Compartimento: <your-compartment-OCID>

  Exemplo: ocid1.compartment.oc1.aaaaaaa...

• Nome da VCN: <your-vcn-name>

  Exemplo: my-vcn

  Abra o menu de navegação e clique em Networking. Em seguida, clique em Virtual Cloud Networks.

• Nome da Sub-rede Pública da VCN: <Public-Subnet-your-vcn-name>

  Exemplo: Public-Subnet-my-vcn

  Abra o menu de navegação e clique em Networking. Em seguida, clique em Virtual Cloud Networks. Clique na VCN criada.

Para criar um aplicativo, siga estas etapas.

1. Abra o menu de navegação e clique em Serviços ao Desenvolvedor. Em Funções, clique em Aplicativos.
2. Selecione seu compartimento na lista suspensa Compartimento.
3. Clique em Criar Aplicativo.
4. Preencha os dados do form.
   • Nome: <your-app-name>
   • VCN: <your-vcn-name>
   • Sub-redes: <Public-Subnet-your-vcn-name>
5. Clique em Criar.

Seu aplicativo foi criado.

1. Abra o menu de navegação e clique em Networking. Em seguida, clique em Virtual Cloud Networks.
2. Clique no nome da VCN que você usou para seu aplicativo Oracle Functions.
3. Com sua nova VCN exibida, clique no link de sub-rede Pública.

   As informações da sub-rede pública são exibidas com as Listas de Segurança na parte inferior da página.

4. Clique no link Lista de Segurança Padrão ou no link da lista de segurança apropriado.

   As Regras de Entrada padrão da sua VCN são exibidas.

5. Clique em Adicionar Regras de Entrada.

   Uma caixa de diálogo Adicionar Regras de Entrada é exibida.

6. Preencha a regra de entrada com as informações a seguir. Depois que todos os dados forem inseridos, clique em Adicionar Regras de Entrada

   Preencha a regra de entrada da seguinte forma:

   • Sem monitoramento de estado: Marcado
   • Tipo de Origem: CIDR
   • CIDR de Origem: 0.0.0.0/0
   • Protocolo IP: TCP
   • Intervalo de Portas de Origem: (leave-blank)
   • Faixa de Portas de Destino: 443
   • Descrição: VCN para aplicativos

   Depois que você clicar em Adicionar Regra de Entrada, serão permitidas conexões HTTPS à sua sub-rede pública.

Em seguida, configure uma política que permita que o API Gateway chame funções.

Primeiro, crie um Grupo Dinâmico para o API Gateway.

1. Abra o menu de navegação e clique em Identidade e Segurança. Em Identity, clique em Dynamic Groups.
2. Clique em Criar Grupo Dinâmico.
3. Preencha as informações a seguir para definir seu grupo dinâmico.
   • Nome: <name-for-your-dynamic-group>
   • Em Regras de Correspondência, use a Regra 1: <the-rule-text>.

   Aqui está o nome da amostra e a regra que você precisa preencher.

   • Nome: api-gtw-func-dynamic-group
   • Em Regras de Correspondência, use a Regra 1: ALL {resource.type = 'ApiGateway', resource.compartment.id = 'ocid1.compartment.<your-compartment-OCID>'}
4. Clique em Criar.

Agora crie a política para o API Gateway.

1. Abra o menu de navegação e clique em Identidade e Segurança. Em Identidade, clique em Políticas.
2. Clique em Criar Política.
3. Para definir sua política, preencha as informações a seguir.
   • Nome: <name-for-your-policy>
   • Descrição: <description-for policy>
   • Compartimento: <name-of-functions-compartment>

   Para a seção Criador de Política:

   • Clique em Mostrar editor manual.
   • Informe a política na caixa de texto, por exemplo:

     Allow dynamic-group  api-gtw-func-dynamic-group to use functions-family in compartment <your-compartment-name>

     Observação
     
     O último parâmetro é o nome do compartimento, não o OCID do compartimento.
4. Clique em Criar.

Você criou uma política para permitir que o API Gateway use Funções.

1. Abra um terminal.
2. Crie um diretório para armazenar suas funções e passe para esse diretório.

   mkdir my-dir-name
   cd my-dir-name                        
                        

3. Crie uma função "Hello World" do Python com Fn.

   fn init --runtime python my-func-name

   Esse comando cria um diretório chamado my-func-name com a função e os arquivos de configuração nele.

4. Passe para o diretório.
5. Implante a função.

   fn -v deploy --app your-app-name

   Várias mensagens são exibidas à medida que as imagens do Docker são criadas, enviadas para o OCIR e por fim implantadas no Oracle Functions.

6. Chame a função.

   fn invoke your-app-name my-func-name

   Retorna: {"message": "Hello World"}

7. Chame a função com um parâmetro.

   echo -n '{"name":"Bob"}' | fn invoke your-app-name my-func-name

   Retorna: {"message": "Hello Bob"}

Para criar um Gateway de API:

1. Abra o menu de navegação e clique em Serviços ao Desenvolvedor. Em Gerenciamento de API, clique em Gateways.
2. Selecione seu compartimento na lista suspensa Compartimento.
3. Clique em Criar Gateway
4. Preencha as informações a seguir para definir seu Gateway de API.
   • Nome: <your-gateway-name>
   • Tipo: <Public>
   • Compartimento: <your-compartment-name>
   • Rede Virtual na Nuvem em <your-vcn-name>: <select-your-vcn>
   • Sub-rede em <your-compartment-name: <your-public-subnet-name>
5. Clique em Criar. Aguarde alguns minutos para que o seu Gateway de API seja criado.

Em seguida, crie uma implantação para seu Gateway de API.

1. Clique em Implantações na seção Recursos do lado esquerdo da tela.
2. Clique em Criar Implantação.
3. Certifique-se de que Totalmente Novo esteja selecionado para o tipo de implantação.
4. Para definir sua implantação, preencha a seção Informações Básicas.
   • Nome: <your-deployment-name>
   • Prefixo de Caminho (exemplo): /tokens
   • Compartimento: <your-compartment-name>
   • Políticas de Solicitação de API: Utilizar valores padrão
   • Políticas de Registro em Log de API: Utilizar valor padrão de Informações
5. Clique em Próximo. A caixa de diálogo Rotas é exibida com a opção Rota 1 selecionada.
6. Para definir sua rota, preencha a seção Rota 1.
   • Campo: <your-route-path>

     Exemplo: /val-token

   • Métodos: GET POST
   • Tipo: Oracle Functions
   • Aplicativo em <your-compartment-name>: Selecione o aplicativo Functions criado.
   • Nome da Função: Selecione a função que você criou na seção de configuração.
7. Clique em Próximo. A caixa de diálogo Revisar é exibida, resumindo as opções feitas.
8. Clique em Criar. Sua implantação é criada.
9. Clique no link Implantações do seu gateway. Copie o ponto final base da implantação criada.

   Por exemplo: https://aaaaa.apigateway.us-ashburn-X.oci.customer-oic.com/tokens

Com o Gateway de API e a implantação criados, agora você pode testar a instalação. Crie um script simples para o comando curl. Para criar o URL para curl, adicione seu caminho de implantação ao seu ponto final.

1. Crie o arquivo de script: touch gtw01.sh && chmod 755 gtw01.sh
2. Adicione o comando curl ao arquivo de script:

   #!/bin/bash
   curl <your-api-gateway-endpoint>/val-token

3. O comando retorna: {"message":"Hello World"}

Você conectou seu Gateway de API a uma função Python com texto padronizado. Em seguida, você atualiza sua função Python para exibir informações transmitidas em uma solicitação HTTP.

Se você observar a função de texto padronizado, sua função Python será semelhante a esta.

import io
import json
import logging

from fdk import response


def handler(ctx, data: io.BytesIO = None):
    name = "World"
    try:
        body = json.loads(data.getvalue())
        name = body.get("name")
    except (Exception, ValueError) as ex:
        logging.getLogger().info('error parsing json payload: ' + str(ex))
    
    logging.getLogger().info("Inside Python Hello World function")
    return response.Response(
       ctx, response_data=json.dumps(
           {"message": "Hello {0}".format(name)}),
       headers={"Content-Type": "application/json"}
    )

Usando esse código como ponto de partida, as seções que vêm depois convertem a função em uma função Python que valida uma chave de API e retorna um token.

O Oracle Functions permite que você armazene dados de configuração no seu contexto que está disponível em sua solicitação. Os dados de configuração podem ser armazenados em um aplicativo ou em uma função. O comando a seguir armazena a chave de API na configuração do seu aplicativo.

• fn config app <your-app-name> FN_API_KEY ABCD

A string "ABCD" é um valor de chave de amostra.

Para obter mais informações sobre como definir valores de configuração da função, consulte o tutorial do Fn Project no contexto de runtime.

Primeiro, atualize o func.py para pacotes necessários.

1. Atualize as instruções import em func.py para a validação de pacotes necessários:

   import io
   import json
   import logging
   import datetime
   
   from datetime import timedelta
   from fdk import response
                   

   O pacote datetime é usado para definir um tempo de expiração para o token retornado.

2. Em seguida, remova o corpo principal da função. O método response e o código relacionado são adicionados de volta à medida que avançamos.

   import io
   import json
   import logging
   import datetime
   
   from datetime import timedelta
   from fdk import response
                           
   
   def handler(ctx, data: io.BytesIO = None):                
   

Agora você está pronto para atualizar a função com o código de validação.

Em seguida, adicione o código para validar a chave de API e retornar um token na resposta. Veja a seguir o código com comentários.

import io
import json
import logging
import datetime

from datetime import timedelta
from fdk import response

def handler(ctx, data: io.BytesIO = None):
    auth_token = "invalid"
    token = "invalid"
    apiKey = "invalid"
    expiresAt = (datetime.datetime.utcnow() + timedelta(seconds=60)).replace(tzinfo=datetime.timezone.utc).astimezone().replace(microsecond=0).isoformat()
    
    try:
        auth_token = json.loads(data.getvalue())
        token = auth_token.get("token")
        
        app_context = dict(ctx.Config())
        apiKey = app_context['FN_API_KEY']
        
        if token == apiKey:
            return response.Response(
                ctx, 
                status_code=200, 
                response_data=json.dumps({"active": True, "principal": "foo", "scope": "bar", "clientId": "1234", "expiresAt": expiresAt, "context": {"username": "wally"}})
            )
    
    except (Exception, ValueError) as ex:
        logging.getLogger().info('error parsing json payload: ' + str(ex))
        pass
    
    return response.Response(
        ctx, 
        status_code=401, 
        response_data=json.dumps({"active": False, "wwwAuthenticate": "API-key"})
    )

• A função handler recebe informações do sistema sobre a solicitação atual por meio dos parâmetros ctx e data.
• A função assume que FN_API_KEY é definido na configuração do aplicativo. Em seguida, a função compara o valor de configuração com o valor de token enviado da solicitação POST curl: -d '{"token":"ABCD"}'.
• Se os valores forem correspondentes, uma mensagem JSON de validação será retornada. Se eles não corresponderem, um código 401 será retornado com dados de erro JSON.

O código da função está concluído. Agora você está pronto para testar a função.

1. Reimplante a função atualizada.
2. Chame a função para garantir que ela esteja funcionando.
3. Atualize o script gtw01.sh para passar os dados POST para o script.

   /bin/bash
   curl -X POST -d '{"token":"ABCD"}' https://aaaaa.apigateway.us-ashburn-X.oci.customer-oic.com/tokens/val-token

4. Execute o script: gtw01.sh | jq
5. Se as chaves de API forem correspondentes, a saída do script será semelhante a:

   {
       "active": true,
       "principal": "foo",
       "scope": "bar",
       "clientId": "1234",
       "expiresAt": "2020-12-16T22:48:50+00:00",
       "context": {
       "username": "wally"
       }
   }

   Se as chaves de API não corresponderem, uma mensagem de erro será retornada.

   {
       "active": false,
       "wwwAuthenticate": "API-key"
   }                        
                       

   Você pode fazer download do código-fonte completo para a função no site Amostras do Oracle Function aqui.

Parabéns, você converteu a função Python de texto padronizado em uma nova função que valida uma chave de API. A função demonstra como os dados podem ser passados para o Gateway de API e processados em uma função.