AnúncioApresentando MongoDB 8.0, o MongoDB mais rápido de todos os tempos! Leia mais >

AnúncioVoyage AI se junta ao MongoDB para impulsionar aplicativos de AI mais precisos e confiáveis no Atlas. Saiba mais >

O que é PyMongo? Introdução ao Python e ao MongoDB

Experimente o Atlas hoje mesmo

PyMongo é o driver oficial do MongoDB para aplicativos Python síncronos. Se você deseja aprender a conectar e usar o MongoDB a partir do seu aplicativo Python, você está no lugar certo. Neste tutorial do PyMongo, vamos criar um aplicativo CRUD (Criar, Ler, Atualizar, Excluir) simples usando FastAPI e MongoDB Atlas. A aplicação será capaz de criar, ler, atualizar e excluir documentos em um banco de dados MongoDB, expondo a funcionalidade por meio de uma REST API. Você pode encontrar o aplicativo finalizado no GitHub.

O que é PyMongo? Introdução ao Python e ao MongoDB

Aplicativo de Gerenciamento CRUD de Livros
Requisitos
Configuração e instalação do projeto
Conecte-se ao seu cluster do MongoDB Atlas
Crie Modelos para Solicitações e Respostas de API
Implementar os pontos de extremidade da API REST
Explore a Página de Documentação da API e Teste os Pontos de Extremidade
Conclusão

Aplicativo de gerenciamento CRUD de livros

Minha maneira favorita de aprender novas tecnologias é construindo algo. É por isso que vamos desenvolver o aplicativo de backend mais trivial, mas útil — um aplicativo CRUD para gerenciar livros. As operações CRUD estarão disponíveis através de uma REST API. A API terá cinco pontos de extremidade:

Code SnippetGET /book: to list all books
GET /book/<id>: to get a book by its ID
POST /book: to create a new book
PUT /book/<id>: to update a book by its ID
DELETE /book/<id>: to delete a book by its ID

Para construir a API, utilizaremos o framework FastAPI. É um framework leve, moderno e fácil de usar para construir APIs. Ele também gera uma documentação da API Swagger que utilizaremos ao testar o aplicativo.

Armazenaremos os livros em um cluster MongoDB Atlas. O MongoDB Atlas é a plataforma de banco de dados como serviço do MongoDB. É baseado em cloud e você pode criar uma conta gratuita e um cluster em minutos, sem instalar nada no seu computador. Usaremos o PyMongo para conectar ao cluster e fazer query de dados.

Requisitos

O projeto finalizado está disponível no GitHub. Você também pode seguir as instruções passo a passo para construir o projeto do zero. Para fazer isso, você precisará do seguinte:

Python 3.6+—Você pode instalá-lo a partir do website do Python.
Um cluster do MongoDB Atlas — você pode criar um cluster gratuito para sempre seguindo o guia Introdução ao Atlas. Conclua as etapas no guia e localize sua string de conexão—você precisará dela para se conectar ao banco de dados a partir do aplicativo.

Configuração e configuração do projeto

Antes de começarmos, criaremos um ambiente virtual Python para isolar o projeto dos pacotes Python instalados globalmente. Usaremos o pacote venv, que acompanha a instalação do Python. Execute o seguinte comando no terminal:

Code Snippetpython3 -m venv env-pymongo-fastapi-crud
source env-pymongo-fastapi-crud/bin/activate

Observação: Pode ser necessário executar este comando usando o executável python3. Isso ocorre porque, em alguns sistemas operacionais, tanto o Python 2 quanto o 3 estão instalados. Depois de fazer login no seu ambiente virtual, o executável python usará a versão 3 automaticamente.

Agora que temos um ambiente virtual, podemos instalar os pacotes necessários. Usaremos o pip — o instalador de pacotes para Python, que também está incluído na sua instalação do Python:

Code Snippet

Em seguida, criaremos um diretório para o nosso projeto, navegaremos até ele e estruturaremos os arquivos necessários para o projeto.

Code Snippetmkdir pymongo-fastapi-crud
cd pymongo-fastapi-crud
touch main.py routes.py models.py .env

Observação: Usaremos comandos shell para criar arquivos e diretórios e navegar por eles. Se preferir, você pode usar um explorador de arquivos gráfico.

Vamos começar implementando um ponto de extremidade raiz / simples que retorna uma mensagem de boas-vindas. Abra o arquivo main.py no seu editor de código favorito e adicione o seguinte:

pymongo-fastapi-crud/main.py

Code Snippetfrom fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Welcome to the PyMongo tutorial!"}

Salve o arquivo e execute o aplicativo usando o pacote uvicorn, que foi instalado junto com o pacote fastapi.

Code Snippet

Você deverá ver a seguinte resposta:

Code SnippetINFO:     Will watch for changes in these directories: ['/Users/you/pymongo-fastapi-crud']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [2465] using watchgod
INFO:     Started server process [2467]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Abra http://127.0.0.1:8000 no seu navegador. Você deve ver a mensagem de boas-vindas.

Muito bem! Temos um servidor em execução. Na seção a seguir, vamos nos conectar ao nosso MongoDB Atlas cluster.

Conecte-se ao seu MongoDB Atlas cluster

Em seguida, precisamos nos conectar ao MongoDB Atlas cluster que criamos anteriormente. Localize sua string de conexão e adicione-a ao .env Migrator. Substitua o nome de usuário e a senha pelas suas credenciais.

pymongo-fastapi-crud/.env

Code SnippetATLAS_URI=mongodb+srv://<username>:<password>@sandbox.lqlql.mongodb.net/?retryWrites=true&w=majority
DB_NAME=pymongo_tutorial

Usaremos o pacote python-dotenv para carregar as variáveis de ambiente ATLAS_URI e DB_NAME do arquivo .env Migrator. Em seguida, usaremos o pacote pymongo para conectar ao cluster do Atlas quando o aplicativo iniciar. Adicionaremos outro manipulador de eventos para fechar a conexão quando o aplicativo for encerrado. Abra o arquivo `main.py` novamente e substitua seu conteúdo pelo seguinte:

Code Snippetfrom fastapi import FastAPI
from dotenv import dotenv_values
from pymongo import MongoClient

config = dotenv_values(".env")

app = FastAPI()

@app.on_event("startup")
def startup_db_client():
    app.mongodb_client = MongoClient(config["ATLAS_URI"])
    app.database = app.mongodb_client[config["DB_NAME"]]
    print("Connected to the MongoDB database!")

@app.on_event("shutdown")
def shutdown_db_client():
    app.mongodb_client.close()

O processo uvicorn detectará a alteração de arquivo e reiniciará o servidor. Você deve ver a mensagem Conectado ao banco de dados MongoDB! no terminal.

Criar modelos para solicitações e respostas de API

O MongoDB possui um modelo de esquema flexível que permite ter documentos com estruturas diferentes dentro da mesma coleção. Na prática, os documentos de uma coleção geralmente compartilham a mesma estrutura. Se necessário, você pode até impor regras de validação por coleção. Não vamos cobrir a validação de banco de dados em nosso tutorial do PyMongo. Em vez disso, garantiremos que os dados que passam pela REST API sejam válidos antes de armazená-los no banco de dados.

Vamos criar alguns modelos para as solicitações e respostas da API e deixar que o FastAPI faça o trabalho pesado por nós. O framework se encarregará da validação, da conversão para os tipos de dados corretos e até mesmo da geração da documentação da API. Abra o arquivo models.py e adicione o seguinte:

pymongo-fastapi-crud/models.py

Code Snippetimport uuid
from typing import Optional
from pydantic import BaseModel, Field

class Book(BaseModel):
    id: str = Field(default_factory=uuid.uuid4, alias="_id")
    title: str = Field(...)
    author: str = Field(...)
    synopsis: str = Field(...)

    class Config:
        allow_population_by_field_name = True
        schema_extra = {
            "example": {
                "_id": "066de609-b04a-4b30-b46c-32537c7f1f6e",
                "title": "Don Quixote",
                "author": "Miguel de Cervantes",
                "synopsis": "..."
            }
        }

class BookUpdate(BaseModel):
    title: Optional[str]
    author: Optional[str]
    synopsis: Optional[str]

    class Config:
        schema_extra = {
            "example": {
                "title": "Don Quixote",
                "author": "Miguel de Cervantes",
                "synopsis": "Don Quixote is a Spanish novel by Miguel de Cervantes..."
            }
        }

Estamos estendendo o BaseModel do pacote pydantic e adicionando os campos aos nossos modelos. Para o modelo Book, temos quatro campos obrigatórios: id, título, autor e sinopse. O campo id é preenchido automaticamente com um UUID (identificador universalmente exclusivo). Também temos um exemplo para o modelo Book que será exibido na documentação da API.

Os campos no modelo BookUpdate são opcionais. Isso nos permitirá realizar atualizações parciais. Não temos um campo de id no modelo BookUpdate porque não queremos permitir que o usuário atualize o id.

Agora que definimos nossos modelos, vamos implementar os pontos de extremidade da REST API e usar os modelos para validar os dados.

Implemente os pontos de extremidade da REST API

É hora da parte divertida! Vamos criar os pontos de extremidade da REST API para nossos livros! Vamos adicionar a implementação dos pontos de extremidade no arquivo routes.py e carregar as rotas no arquivo main.py. Começaremos inicializando um objeto APIRouter em routes.py:

pymongo-fastapi-crud/routes.py

Code Snippetfrom fastapi import APIRouter, Body, Request, Response, HTTPException, status
from fastapi.encoders import jsonable_encoder
from typing import List

from models import Book, BookUpdate

router = APIRouter()

Como você percebe, estamos importando o APIRouter do pacote FastAPI. Utilizaremos este objeto para definir os pontos de extremidade da nossa REST API. Também estamos importando os modelos Book e BookUpdate que definimos anteriormente.

publicação /book

O primeiro ponto de extremidade que implementaremos é o ponto de extremidade de publicação /books para criar um novo livro. Adicione o seguinte após a linha router = APIRouter():

pymongo-fastapi-crud/routes.py

Code Snippet@router.post("/", response_description="Create a new book", status_code=status.HTTP_201_CREATED, response_model=Book)
def create_book(request: Request, book: Book = Body(...)):
    book = jsonable_encoder(book)
    new_book = request.app.database["books"].insert_one(book)
    created_book = request.app.database["books"].find_one(
        {"_id": new_book.inserted_id}
    )

    return created_book

A rota é / porque prefixaremos todos os pontos de extremidade de livros com /books. A response_description será exibida na documentação da API. O status_code é o código de status HTTP retornado quando a solicitação é bem-sucedida. Usamos o modelo Book para validar os dados transmitidos no corpo da solicitação e a resposta que enviamos de volta. O FastAPI realiza a validação para nós. No corpo da função, utilizamos o método insert_one() do PyMongo para inserir o novo livro na coleção books. Estamos utilizando o método find_one() para obter o livro recém-criado do banco de dados. Você pode ler mais sobre os métodos insert_one() e find_one() no artigo da documentação do PyMongo para operações em nível de coleção.

Por fim, estamos retornando o livro criado.

GET /book

Em seguida, implementaremos o ponto de extremidade GET /book para retornar uma lista com todos os documentos na coleção de livros. Anexe o seguinte ao final do arquivo routes.py:

pymongo-fastapi-crud/routes.py

Code Snippet@router.get("/", response_description="List all books", response_model=List[Book])
def list_books(request: Request):
    books = list(request.app.database["books"].find(limit=100))
    return books

Para o modelo de resposta, estamos utilizando o tipo List[Book]. Isso significa que a resposta será uma lista de objetos Book. Também estamos utilizando o método find() para recuperar no máximo 100 livros do banco de dados. Para aprender mais sobre o limite e os outros parâmetros do método find(), consulte a página dedicada da documentação do PyMongo.

GET /book/{id}

Vamos criar outro ponto de extremidade GET para recuperar um único livro pelo seu id. Adicione o seguinte ao final do arquivo routes.py:

pymongo-fastapi-crud/routes.py

Code Snippet@router.get("/{id}", response_description="Get a single book by id", response_model=Book)
def find_book(id: str, request: Request):
    if (book := request.app.database["books"].find_one({"_id": id})) is not None:
        return book
    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Book with ID {id} not found")

Aqui, estamos usando o método find_one() para recuperar um único livro do banco de dados. Se o livro for encontrado, nós o devolveremos. Se o livro não for encontrado, levantaremos uma HTTPException com um código de status 404 Not Found e uma mensagem apropriada.

PUT /book/{id}

Indiscutivelmente, o ponto de extremidade mais importante para nossa REST API é o ponto de extremidade PUT /book/{id}. Este ponto de extremidade nos permite atualizar um único livro. Adicione a implementação ao final do arquivo routes.py:

pymongo-fastapi-crud/routes.py

Code Snippet@router.put("/{id}", response_description="Update a book", response_model=Book)
def update_book(id: str, request: Request, book: BookUpdate = Body(...)):
    book = {k: v for k, v in book.dict().items() if v is not None}
    if len(book) >= 1:
        update_result = request.app.database["books"].update_one(
            {"_id": id}, {"$set": book}
        )

        if update_result.modified_count == 0:
            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Book with ID {id} not found")

    if (
        existing_book := request.app.database["books"].find_one({"_id": id})
    ) is not None:
        return existing_book

    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Book with ID {id} not found")

Vamos analisar o código. Primeiro, estamos criando um objeto que utilizaremos para atualizar o livro. Então, se houver algum campo no objeto book, utilizamos o método update_one() para atualizar o livro no banco de dados. É importante observar que estamos usando o operador de atualização $set para garantir que apenas os campos especificados sejam atualizados em vez de reescrever todo o documento.

Em seguida, verificamos o atributo modified_count do update_result para confirmar que o livro foi atualizado. Se for esse o caso, estamos usando o método find_one() para recuperar o livro atualizado do banco de dados e retorná-lo.

Se não houver campos no objeto book, estamos apenas retornando o livro existente. No entanto, se o livro não for encontrado, estamos a gerar uma HTTPException com um código de estado 404 Não Encontrado.

excluir /book/{id}

O último ponto de extremidade que implementaremos é o excluir /book/{id} ponto de extremidade para excluir um único livro pelo seu id. Adicione o seguinte ao final do arquivo routes.py:

pymongo-fastapi-crud/routes.py

Code Snippet@router.delete("/{id}", response_description="Delete a book")
def delete_book(id: str, request: Request, response: Response):
    delete_result = request.app.database["books"].delete_one({"_id": id})

    if delete_result.deleted_count == 1:
        response.status_code = status.HTTP_204_NO_CONTENT
        return response

    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Book with ID {id} not found")

A única coisa notável aqui é que, se o livro foi excluído, estamos retornando um código de status 204 Sem Conteúdo. Este é um código de status de sucesso que indica que a solicitação foi bem-sucedida e não há conteúdo a ser enviado no corpo da carga útil da resposta.

Registre o

Finalmente, precisamos registrar os pontos de extremidade /book. Abra o arquivo main.py, importe o módulo routes e registre o roteador de livros. Sua versão final do arquivo main.py deve ser:

pymongo-fastapi-crud/main.py

Code Snippetfrom fastapi import FastAPI
from dotenv import dotenv_values
from pymongo import MongoClient
from routes import router as book_router

config = dotenv_values(".env")

app = FastAPI()

@app.on_event("startup")
def startup_db_client():
    app.mongodb_client = MongoClient(config["ATLAS_URI"])
    app.database = app.mongodb_client[config["DB_NAME"]]

@app.on_event("shutdown")
def shutdown_db_client():
    app.mongodb_client.close()

app.include_router(book_router, tags=["books"], prefix="/book")

Explore a página de documentação da API e teste os pontos de extremidade

Certifique-se de que o processo uvicorn ainda esteja em execução antes de continuar. Caso não esteja, você pode iniciar com o mesmo comando no terminal:

Code Snippet

Navegue até o URL http://localhost:8000/docs no seu navegador. Esta é a página de documentação da API que a FastAPI e o Swagger geraram para nós!

Visualizamos todos os endpoints que criamos e podemos até mesmo enviar solicitações diretamente desta página! Abra a aba publicação e clique no botão Tentar. Você deve ver um corpo de solicitação preenchido com nosso livro de exemplo. Clique em Executar para enviar a solicitação. Você deverá ver uma resposta bem-sucedida com o livro que criamos. Você pode obter o id do livro da resposta e utilizá-lo em um dos outros pontos de extremidade: GET /book/{id}, PUT /book/{id} ou DELETE /book/{id}.

Mas e se tentarmos criar o mesmo registro de livro duas vezes? Receberemos uma resposta de erro interno do servidor 500. Se verificarmos o terminal onde o processo do servidor está em execução, deveremos ver uma mensagem de erro contendo o seguinte:

Code Snippetpymongo.errors.DuplicateKeyError: E11000 duplicate key error collection: pymongo_tutorial.books index: _id

Recebemos um erro de chave duplicada porque tentamos inserir um livro com o mesmo campo _id duas vezes. O campo _id é um índice único que o MongoDB cria para cada coleção. Não podemos ter dois livros com o mesmo _id. O problema real aqui é que não estamos lidando com esse erro em nosso código. O erro 'propaga-se' e o servidor responde com um 500 Internal Server Error. Como exercício, você pode elaborar uma resposta adequada para enviar ao cliente e resolver esse erro.

Você também pode testar as regras de validação que criamos. Por exemplo, tente remover o campo de título obrigatório do corpo da solicitação e clique em Executar. Você deverá ver uma mensagem de erro informando que o campo de título é obrigatório.

A página de documentação da API gerada é extremamente útil para experimentar diferentes cenários e observar o comportamento da API. Divirta-se explorando a API que desenvolvemos!

Conclusão

Neste tutorial, vimos como criar uma aplicação CRUD simples com FastAPI e PyMongo, o driver oficial do MongoDB para aplicações Python síncronas. Também vimos como podemos configurar rapidamente um MongoDB Atlas cluster gratuito e nos conectar a ele. MongoDB Atlas é muito mais do que apenas um banco de dados MongoDB em nuvem. Por exemplo, você pode facilmente estender sua API para fornecer uma pesquisa de texto completo com o Atlas Search. Todos esses serviços estão disponíveis no MongoDB Atlas. Se você quiser experimentá-los, crie sua conta gratuita.

Perguntas frequentes

PyMongo é o driver oficial do MongoDB para aplicativos Python síncronos. Você pode conectar-se a uma instância do MongoDB e consultar dados. É uma ótima ferramenta para construir aplicativos que interagem com o MongoDB.

PyMongo é um pacote Python. Você pode instalá-lo com o "pip": "python -m pip install pymongo[srv]".

Após instalar o PyMongo, você pode importá-lo para seu aplicativo, conectar-se a uma instância do MongoDB e começar a consultar dados.

PyMongo é o driver oficial do MongoDB para Python, enquanto o MongoEngine é um ORM (Object Relational Mapper) que utiliza o PyMongo internamente. O PyMongo é oficialmente suportado e recomendado pelo MongoDB. Leia mais sobre as diferenças entre os dois no artigodedicado

Comece a usar o Atlas hoje mesmo

Comece em segundos. Nossos grupos gratuitos oferecem 512 MB de armazenamento para que você possa usar dados de amostragem e conhecer mais sobre a nossa plataforma.

Experimente grátisFale com a equipe de vendas

COMECE A USAR:

Mais de 125 regiões em todo o mundo
Amostragem de conjuntos de dados
Autenticação sempre ativada
Criptografia de ponta a ponta

Ferramentas de linha de comando

O que é PyMongo? Introdução ao Python e ao MongoDB

Aplicativo de gerenciamento CRUD de livros

Requisitos

Configuração e configuração do projeto

Conecte-se ao seu MongoDB Atlas cluster

Criar modelos para solicitações e respostas de API

Implemente os pontos de extremidade da REST API

publicação /book

GET /book

GET /book/{id}

PUT /book/{id}

excluir /book/{id}

Registre o

Explore a página de documentação da API e teste os pontos de extremidade

Conclusão

Perguntas frequentes

O que você pode fazer com o PyMongo?

Como posso baixar e instalar o PyMongo?

Como se faz para usar o PyMongo?

Devo usar PyMongo ou MongoEngine?

Comece a usar o Atlas hoje mesmo