O autor selecionou a Mozilla Foundation para receber uma doação como parte do programa Write for DOnations.
Introdução
Como a demanda por um desenvolvimento full-stack continua crescendo, os frameworks Web estão tornando os fluxos de trabalho menos trabalhosos e mais eficientes; o Django é um desses frameworks. O Django vem sendo usado em sites bastante conhecidos como o Mozilla, o Pinterest e o Instagram. Ao contrário do Flask, que é um microframework neutro, o pacote PyPI do Django inclui tudo o que você precisa para o desenvolvimento full-stack; não há necessidade de configurar um banco de dados ou um painel de controle para o desenvolvimento.
Um uso comum para o Django é usá-lo para exibir informações de APIs (como os posts do Instagram ou os repositórios do GitHub) em seus próprios sites e aplicativos Web. Embora isso seja possível com outros frameworks, a filosofia do Django “baterias inclusas” significa que haverá menos problemas e menos pacotes necessários para criar o mesmo resultado.
Neste tutorial, você criará um projeto Django que exibirá as informações do Droplet da sua conta da DigitalOcean usando a DigitalOcean v2 API. Especificamente, você criará um site que exibirá uma tabela de Droplets listando cada um dos endereços IP, IDs, regiões de hospedagem e recursos. Seu site usará o BulmaCSS para estilizar a página, para que você possa se concentrar no desenvolvimento, ao mesmo tempo que proporciona algo bonito para se ver no final.
Assim que terminar este tutorial, você terá um projeto Django que consegue produzir uma página Web parecida com esta:
Pré-requisitos
Antes de iniciar este guia, será necessário o seguinte:
- Uma conta da DigitalOcean com pelo menos um Droplet e um token de acesso pessoal. Certifique-se de gravar o token em um lugar seguro; você precisará dele mais tarde neste tutorial.
- Estar familiarizado com a criação de solicitações a APIs. Para um tutorial compreensivo sobre como trabalhar com APIs, consulte Como usar as APIs Web em Python3.
- Um ambiente virtual local para o Python, para manter as dependências. Neste tutorial, usaremos o nome
do_django_apipara nosso diretório de projeto eenvpara o nosso ambiente virtual. - Estar familiarizado com a lógica de modelos do Django para renderizar páginas com dados de API.
- Estar familiarizado com a lógica de visualização do Django para o processamento dos dados recebidos da API e fornecimento deles a um modelo para renderização.
Passo 1 — Criando um projeto Django básico
Do ambiente virtual env, instale o Django:
Agora, você pode iniciar um projeto Django e executar alguns comandos de configuração inicial.
Use django-admin startproject <name> para criar um subdiretório na pasta do projeto nomeada com base no seu projeto Django e, em seguida, mude para aquele diretório.
- django-admin startproject do_django_project
- cd do_django_project
Assim que ele for criado, dentro deste subdiretório, você encontrará o manage.py, que é a maneira usual de interagir com o Django e executar seu projeto. Use migrate para atualizar o banco de dados de desenvolvimento do Django:
- python3 manage.py migrate
Você verá um resultado que se parece com este após a atualização do banco de dados:
Output
Operations to perform:
Apply all migrations: admin, auth, contenttypes, sessions
Running migrations:
Applying contenttypes.0001_initial... OK
Applying auth.0001_initial... OK
Applying admin.0001_initial... OK
Applying admin.0002_logentry_remove_auto_add... OK
Applying admin.0003_logentry_add_action_flag_choices... OK
Applying contenttypes.0002_remove_content_type_name... OK
Applying auth.0002_alter_permission_name_max_length... OK
Applying auth.0003_alter_user_email_max_length... OK
Applying auth.0004_alter_user_username_opts... OK
Applying auth.0005_alter_user_last_login_null... OK
Applying auth.0006_require_contenttypes_0002... OK
Applying auth.0007_alter_validators_add_error_messages... OK
Applying auth.0008_alter_user_username_max_length... OK
Applying auth.0009_alter_user_last_name_max_length... OK
Applying auth.0010_alter_group_name_max_length... OK
Applying auth.0011_update_proxy_permissions... OK
Applying sessions.0001_initial... OK
Em seguida, utilize o comando runserver para executar o projeto, para que você possa testá-lo:
- python3 manage.py runserver
Quando o servidor for iniciado, o resultado se parecerá com este:
Output
Watching for file changes with StatReloader
Performing system checks...
System check identified no issues (0 silenced).
September 22, 2019 - 22:57:07
Django version 2.2.5, using settings 'do_django_project.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
Agora, você tem um projeto Django básico e um servidor de desenvolvimento em funcionamento. Para visualizar seu servidor de desenvolvimento em funcionamento, visite o 127.0.0.1:8000 em um navegador. Ele exibirá a página inicial do Django:
Em seguida, você criará um app do Django e configurará seu projeto para executar uma visualização a partir do app, para que você veja algo mais interessante que a página padrão.
Passo 2 — Criando um aplicativo Django básico
Neste passo, você criará o esqueleto do app que terá os resultados do seu Droplet. Mais tarde, você voltará para este aplicativo assim que tiver configurado a chamada de API para preenchê-lo com dados.
Certifique-se de estar no diretório do_django_project e crie um app Django usando o seguinte comando:
- python3 manage.py startapp display_droplets
Agora, você precisa adicionar o novo app a INSTALLED_APPS no arquivo settings.py, para o Django reconhecê-lo. O settings.py é um arquivo de configuração do Django que está localizado dentro de outro subdiretório no projeto Django e tem o mesmo nome que a pasta do projeto (do_django_project). O Django criou ambas as pastas para você. Vá até o diretório do_django_project:
Edite o settings.py no editor da sua escolha:
Adicione seu novo app à seção INSTALLED_APPS do arquivo:
do_django_api/do_django_project/do_django_project/settings.py
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
# The new app
'display_droplets',
]
Salve e feche o arquivo quando terminar.
Função de visualização GetDroplets
Em seguida, você criará uma função, GetDroplets, dentro do arquivo views.py do app display_droplets. Essa função renderizará o modelo que você usará para exibir os dados do Droplet, como o context, a partir da API. O context é um dicionário que é usado para tirar os dados do código do Python e enviá-los para um modelo HTML, para que ele possa ser exibido em uma página Web.
Vá até o diretório display_droplets:
- cd ..
- cd display_droplets
Abra o views.py para edição:
Adicione o código a seguir ao arquivo:
do_django_api/do_django_project/display_droplets/views.py
from django.views.generic import TemplateView
class GetDroplets(TemplateView):
template_name = 'droplets.html'
def get_context_data(self, *args, **kwargs):
pass
Salve e feche o arquivo.
Mais tarde, você preencherá essa função e criará o arquivo droplets.html, mas primeiro vamos configurar o urls.py para chamar essa função quando você visitar o diretório raiz do servidor de desenvolvimento (127.0.0.1:8000).
Volte para o diretório do_django_project:
- cd ..
- cd do_django_project
Abra o urls.py para edição:
Adicione uma instrução import para o GetDroplets e, em seguida, adicione um caminho adicional para o urlpatterns que apontará para a nova visualização.
do_django_api/do_django_project/do_django_project/urls.py
from django.contrib import admin
from django.urls import path
from display_droplets.views import GetDroplets
urlpatterns = [
path('admin/', admin.site.urls),
path('', GetDroplets.as_view(template_name='droplets.html'), name='Droplet View'),
]
Se quiser fazer seus próprios caminhos personalizados, o primeiro parâmetro é o URL (tal como example.com/**admin**), o segundo parâmetro é a função a ser chamada para produzir a página Web e o terceiro é apenas um nome para o caminho.
Salve e feche o arquivo.
Modelo de Droplets
Em seguida, você trabalhará com os modelos. Os modelos são arquivos HTML que o Django usa para criar páginas Web. Neste caso, você usará um modelo para construir uma página HTML que exibe os dados da API.
Volte para o diretório display_droplets:
- cd ..
- cd display_droplets
Dentro deste diretório, crie uma pasta template (modelo) e vá para esse diretório:
- mkdir templates
- cd templates
Crie o droplets.html e abra-o para edição:
Para evitar que você tenha que escrever qualquer tipo de CSS para este projeto, usaremos o Bulma CSS, pois é um framework CSS leve e gratuito que permite que você crie páginas Web de aparência limpa, apenas adicionando alguns atributos de classe ao HTML.
Agora, vamos criar um modelo com uma barra de navegação básica. Adicione o código a seguir ao arquivo droplets.html:
do_django_api/do_django_project/display_droplets/templates/droplets.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>DigitalOcean Droplets</title>
<link crossorigin="anonymous"
href="https://cdnjs.cloudflare.com/ajax/libs/bulma/0.7.4/css/bulma.min.css"
integrity="sha256-8B1OaG0zT7uYA572S2xOxWACq9NXYPQ+U5kHPV1bJN4="
rel="stylesheet"/>
<link rel="shortcut icon" type="image/png" href="https://assets.digitalocean.com/logos/favicon.png"/>
</head>
<body>
<nav aria-label="main navigation" class="navbar is-light" role="navigation">
<div class="navbar-brand">
<div class="navbar-item">
<img atl="DigitalOcean" src="https://assets.digitalocean.com/logos/DO_Logo_icon_blue.png"
style="margin-right: 0.5em;">Droplets
</div>
</div>
</nav>
</body>
</html>
Salve e feche o arquivo.
Esse código importa o Bulma para o HTML boilerplate e cria uma barra nav que exibe “Droplets”.
Recarregue sua aba do navegador para visualizar as alterações que você fez no modelo.
Até agora, você ainda não mexeu em nada relacionado às APIs; você criou uma fundação para o projeto. Em seguida, essa página será posta em uso, fazendo uma chamada de API e apresentando os dados do Droplet.
Passo 3 — Fazendo a chamada de API
Neste passo, você configurará uma chamada de API e enviará os dados do Droplet como contexto para o modelo exibir em uma tabela.
Como obter dados do Droplet
Navegue novamente para o diretório do app display_droplets:
Instale a biblioteca requests (solicitações) para que você possa falar com a API:
A biblioteca requests permite que seu código solicite dados de APIs e adicione cabeçalhos (dados adicionais enviados juntamente com nossa solicitação).
Em seguida, você criará um arquivo services.py, que é onde fará a chamada API. Essa função usará requests para falar com https://api.ddigitalocean.com/v2/droplets e adicionará a uma lista cada Droplet presente no arquivo JSON retornado.
Abra o services.py para edição:
Adicione o código a seguir ao arquivo:
do_django_api/do_django_project/display_droplets/services.py
import os
import requests
def get_droplets():
url = 'https://api.digitalocean.com/v2/droplets'
r = requests.get(url, headers={'Authorization':'Bearer %s' % 'access_token'})
droplets = r.json()
droplet_list = []
for i in range(len(droplets['droplets'])):
droplet_list.append(droplets['droplets'][i])
return droplet_list
Dentro da função get_droplets, duas coisas ocorrem: uma solicitação é feita e os dados são analisados. O url contém o URL que solicita os dados do Droplet da API da DigitalOcean. O r armazena os dados solicitados.
requests necessita de dois parâmetros neste caso: o url e o headers. Se quiser dados de uma API diferente, você substituirá o valor url pelo URL apropriado. O headers envia seu token de acesso à DigitalOcean, para que eles saibam que você tem permissão para fazer a solicitação e para qual conta a solicitação está sendo feita.
Os droplets contêm a informação da variável r, mas agora ela foi convertida de JSON, o formato em que a API envia informações, para um dicionário que é fácil de usar em um loop for.
As três linhas seguintes criam uma matriz, droplet_list[]. Em seguida, um loop for itera sobre as informações em droplets e adiciona cada item à lista. Todas as informações obtidas da API e armazenadas em droplets podem ser encontradas nos Docs de desenvolvedor da DigitalOcean.
Nota: não se esqueça de substituir o access_token pelo seu token de acesso. Além disso, mantenha-o seguro e nunca publique esse token na internet.
Salve e feche o arquivo.
Como proteger seu token de acesso
Você sempre deve esconder seu token de acesso, mas se alguém quiser executar seu projeto, deve haver uma maneira fácil para que eles adicionem seu próprio token de acesso sem precisar editar o código Python. O DotENV é a solução, já que as variáveis são mantidas em um arquivo .env que pode ser convenientemente editado.
Volte para o diretório do_django_project:
Para começar a trabalhar com variáveis de ambiente, instale o python-dotenv:
- pip install python-dotenv
Assim que estiver instalado, é necessário configurar o Django para lidar com variáveis de ambiente, de forma que você possa referenciá-las em código. Para fazer isso, é preciso adicionar algumas linhas de código em manage.py e wsgi.py.
Abra o manage.py para edição:
Adicione as linhas a seguir:
do_django_api/do_django_project/manage.py
"""Django's command-line utility for administrative tasks."""
import os
import sys
import dotenv
def main():
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'do_django_project.settings')
try:
from django.core.management import execute_from_command_line
except ImportError as exc:
raise ImportError(
"Couldn't import Django. Are you sure it's installed and "
"available on your PYTHONPATH environment variable? Did you "
"forget to activate a virtual environment?"
) from exc
execute_from_command_line(sys.argv)
if __name__ == '__main__':
main()
dotenv.load_dotenv(
os.path.join(os.path.dirname(__file__), '.env')
)
Adicionar isso em manage.py significa que, quando você emitir comandos para o Django em desenvolvimento, ele processará as variáveis de ambiente do seu arquivo .env.
Salve e feche o arquivo.
Se precisar lidar com variáveis de ambiente em seus projetos de produção, faça isso a partir do arquivo wsgi.py. Vá até o diretório do_django_project:
E abra o wsgi.py para edição:
Adicione o código a seguir ao wsgi.py:
do_django_api/do_django_project/do_django_project/wsgi.py
import os
import dotenv
from django.core.wsgi import get_wsgi_application
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'do_django_project.settings')
dotenv.load_dotenv(
os.path.join(os.path.dirname(os.path.dirname(__file__)), '.env')
)
application = get_wsgi_application()
Este fragmento de código tem um os.path.dirname() adicional, pois o wsgi.py precisa procurar dois diretórios para encontrar o arquivo .env. Este fragmento não é o mesmo que foi usado para o manage.py.
Salve e feche o arquivo.
Agora, você pode utilizar uma variável de ambiente em services.py em vez do seu token de acesso. Volte para o diretório display_droplets:
- cd ..
- cd display_droplets
Abra o services.py para edição:
Agora, substitua seu token de acesso por uma variável de ambiente:
do_django_api/display_droplets/services.py
import os
import requests
def get_droplets():
url = "https://api.digitalocean.com/v2/droplets"
r = requests.get(url, headers={'Authorization':'Bearer %s' % os.getenv('DO_ACCESS_TOKEN')})
droplets = r.json()
droplet_list = []
for i in range(len(droplets['droplets'])):
droplet_list.append(droplets['droplets'][i])
return droplet_list
Salve e feche o arquivo.
O próximo passo é criar um arquivo .env. Volte para o diretório do_django_project:
Crie um arquivo .env e entre no arquivo para edição:
No .env, adicione seu token como a variável DO_ACCESS_TOKEN:
do_django_api/do_django_project/.env
DO_ACCESS_TOKEN=access_token
Salve e feche o arquivo.
Nota: adicione .env ao seu arquivo .gitignore, de modo que ele nunca seja incluído em suas confirmações.
A conexão de API agora está definida e configurada, e você também protegeu seu token de acesso. É hora de apresentar para o usuário as informações que você recuperou.
Passo 4 — Habilitando dados do Droplet em visualizações e modelos
Agora que pode fazer as chamadas de API, você precisa enviar os dados do Droplet ao modelo para renderização. Vamos retornar ao stub da função, GetDroplets, que você criou antes em views.py. Na função, será enviado o droplet_list como contexto para o modelo droplets.html
Vá até o diretório display_droplets:
Abra o views.py para edição:
Adicione o código a seguir ao views.py:
do_django_api/do_django_project/display_droplets/views.py
from django.shortcuts import render
from django.views.generic import TemplateView
from .services import get_droplets
class GetDroplets(TemplateView):
template_name = 'droplets.html'
def get_context_data(self, *args, **kwargs):
context = {
'droplets' : get_droplets(),
}
return context
As informações enviadas para o modelo droplets.html são processadas por meio do dicionário context. Por isso, o droplets age como uma chave e a matriz retornada de get_droplets() age como um valor.
Salve e feche o arquivo.
Como exibir os dados no modelo
Dentro do modelo droplets.html, você criará uma tabela e a preencherá com os dados do droplet.
Vá até o diretório templates:
Abra o droplets.html para edição:
Adicione o código a seguir após o elemento nav em droplets.html:
do_django_api/do_django_project/display_droplets/templates/droplets.html
<table class="table is-fullwidth is-striped is-bordered">
<thead>
<tr>
<th>Name</th>
<th>IPv4 Address(es)</th>
<th>Id</th>
<th>Region</th>
<th>Memory</th>
<th>CPUs</th>
<th>Disk Size</th>
</tr>
</thead>
<tbody>
{% for droplet in droplets %}
<tr>
<th>{{ droplet.name }}</th>
{% for ip in droplet.networks.v4 %}
<td>{{ ip.ip_address }}</td>
{% endfor %}
<td>{{ droplet.id }}</td>
<td>{{ droplet.region.name }}</td>
<td>{{ droplet.memory }}</td>
<td>{{ droplet.vcpus }}</td>
<td>{{ droplet.disk }}</td>
</tr>
{% endfor %}
</tbody>
</table>
{% for droplet in droplets %} ... {% endfor %} é um loop que itera através da matriz de Droplets recuperados de views.py. Cada Droplet é inserido em uma linha de tabela. As várias linhas {{ droplet.<Attribute>}} recuperam o atributo para cada Droplet no loop e o inserem em uma célula da tabela.
Salve e feche o arquivo.
Recarregue o navegador e você verá uma lista de Droplets.
Agora, é possível lidar com a API da DigitalOcean dentro dos seus projetos do Django. Você pegou os dados recuperados da API e anexou-os no modelo que criou anteriormente, para exibir as informações de uma maneira legível e flexível.
Conclusão
Neste artigo, você construiu um projeto Django que exibe as informações do Droplet na API da DigitalOcean com a estilização do Bulma CSS. Você aprendeu três habilidades importantes seguindo este tutorial:
- Como lidar com solicitações de API em Python, usando os módulos
requestsejson. - Como exibir dados de API em um projeto Django usando as lógicas
viewetemplate. - Como lidar com segurança com seus tokens de API usando o
dotenvno Django.
Agora que você foi introduzido ao processamento das APIs no Django, é possível criar um projeto próprio usando outra funcionalidade da API da DigitalOcean ou de uma outra API completamente diferente. Também é possível verificar outros tutoriais do Django ou um tutorial semelhante com o framework React.