* Verifique se estå tudo certo na tradução.
* Se necessĂĄrio, melhore seu prompt especĂfico do idioma, o prompt geral ou o documento em inglĂȘs.
* Em seguida, corrija manualmente os problemas restantes na tradução, para que fique uma boa tradução.
-* Retraduzir, tendo a boa tradução no lugar. O resultado ideal seria que o LLM nĂŁo fizesse mais mudanças na tradução. Isso significa que o prompt geral e o seu prompt especĂfico do idioma estĂŁo tĂŁo bons quanto possĂvel (Ă s vezes farĂĄ algumas mudanças aparentemente aleatĂłrias, a razĂŁo Ă© que [LLMs nĂŁo sĂŁo algoritmos determinĂsticos](https://doublespeak.chat/#/handbook#deterministic-output)).
+* Retraduza, tendo a boa tradução no lugar. O resultado ideal seria que o LLM nĂŁo fizesse mais mudanças na tradução. Isso significa que o prompt geral e o seu prompt especĂfico do idioma estĂŁo tĂŁo bons quanto possĂvel (Ă s vezes farĂĄ algumas mudanças aparentemente aleatĂłrias, a razĂŁo Ă© que [LLMs nĂŁo sĂŁo algoritmos determinĂsticos](https://doublespeak.chat/#/handbook#deterministic-output)).
Os testes:
### O abbr fornece uma frase completa { #the-abbr-gives-a-full-phrase }
-* <abbr title="Getting Things Done â Fazer as Coisas">GTD</abbr>
-* <abbr title="less than â menos que"><code>lt</code></abbr>
-* <abbr title="XML Web Token â Token Web XML">XWT</abbr>
-* <abbr title="Parallel Server Gateway Interface â Interface de Gateway de Servidor Paralelo">PSGI</abbr>
+* <abbr title="Getting Things Done - Fazer as Coisas">GTD</abbr>
+* <abbr title="less than - menos que"><code>lt</code></abbr>
+* <abbr title="XML Web Token - Token Web XML">XWT</abbr>
+* <abbr title="Parallel Server Gateway Interface - Interface de Gateway de Servidor Paralelo">PSGI</abbr>
### O abbr fornece uma frase completa e uma explicação { #the-abbr-gives-a-full-phrase-and-an-explanation }
-* <abbr title="Mozilla Developer Network â Rede de Desenvolvedores da Mozilla: documentação para desenvolvedores, escrita pelo pessoal do Firefox">MDN</abbr>
-* <abbr title="Input/Output â Entrada/SaĂda: leitura ou escrita em disco, comunicaçÔes de rede.">I/O</abbr>.
+* <abbr title="Mozilla Developer Network - Rede de Desenvolvedores da Mozilla: documentação para desenvolvedores, escrita pelo pessoal do Firefox">MDN</abbr>
+* <abbr title="Input/Output: leitura ou escrita em disco, comunicaçÔes de rede.">I/O</abbr>.
////
VocĂȘ tambĂ©m pode utilizar `from starlette.responses import JSONResponse`.
-O **FastAPI** disponibiliza o `starlette.responses` como `fastapi.responses` apenas por conveniĂȘncia para vocĂȘ, o programador. PorĂ©m a maioria dos retornos disponĂveis vem diretamente do Starlette. O mesmo com `status`.
+O **FastAPI** disponibiliza o `starlette.responses` como `fastapi.responses` apenas por conveniĂȘncia para vocĂȘ, o programador. PorĂ©m a maioria das respostas disponĂveis vem diretamente do Starlette. O mesmo com `status`.
///
## OpenAPI e documentação da API { #openapi-and-api-docs }
-Se vocĂȘ retorna cĂłdigos de status adicionais e retornos diretamente, eles nĂŁo serĂŁo incluĂdos no esquema do OpenAPI (a documentação da API), porque o FastAPI nĂŁo tem como saber de antemĂŁo o que serĂĄ retornado.
+Se vocĂȘ retorna cĂłdigos de status adicionais e respostas diretamente, eles nĂŁo serĂŁo incluĂdos no esquema do OpenAPI (a documentação da API), porque o FastAPI nĂŁo tem como saber de antemĂŁo o que serĂĄ retornado.
-Mas vocĂȘ pode documentar isso no seu cĂłdigo, utilizando: [Retornos Adicionais](additional-responses.md).
+Mas vocĂȘ pode documentar isso no seu cĂłdigo, utilizando: [Respostas Adicionais](additional-responses.md).
# DependĂȘncias avançadas { #advanced-dependencies }
+
## DependĂȘncias parametrizadas { #parameterized-dependencies }
Todas as dependĂȘncias que vimos atĂ© agora sĂŁo funçÔes ou classes fixas.
Isso ainda é suportado graças ao **Pydantic**, pois ele tem [suporte interno para `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel).
-EntĂŁo, mesmo com o cĂłdigo acima que nĂŁo usa Pydantic explicitamente, o FastAPI estĂĄ usando Pydantic para converter essas dataclasses padrĂŁo para a versĂŁo do Pydantic.
+EntĂŁo, mesmo com o cĂłdigo acima que nĂŁo usa Pydantic explicitamente, o FastAPI estĂĄ usando Pydantic para converter essas dataclasses padrĂŁo para a prĂłpria versĂŁo de dataclasses do Pydantic.
E claro, ele suporta o mesmo:
# Eventos de lifespan { #lifespan-events }
+
VocĂȘ pode definir a lĂłgica (cĂłdigo) que deve ser executada antes da aplicação **inicializar**. Isso significa que esse cĂłdigo serĂĄ executado **uma vez**, **antes** de a aplicação **começar a receber requisiçÔes**.
Da mesma forma, vocĂȘ pode definir a lĂłgica (cĂłdigo) que deve ser executada quando a aplicação estiver **encerrando**. Nesse caso, esse cĂłdigo serĂĄ executado **uma vez**, **depois** de possivelmente ter tratado **vĂĄrias requisiçÔes**.
///
-## Geradores de SDK dos patrocinadores do FastAPI { #sdk-generators-from-fastapi-sponsors }
-
-Esta seção destaca soluçÔes **financiadas por investimento** e **com suporte de empresas** que patrocinam o FastAPI. Esses produtos fornecem **funcionalidades adicionais** e **integraçÔes** além de SDKs gerados com alta qualidade.
-
-Ao âš [**patrocinar o FastAPI**](../help-fastapi.md#sponsor-the-author) âš, essas empresas ajudam a garantir que o framework e seu **ecossistema** continuem saudĂĄveis e **sustentĂĄveis**.
-
-O patrocĂnio tambĂ©m demonstra um forte compromisso com a **comunidade** FastAPI (vocĂȘ), mostrando que elas se importam nĂŁo apenas em oferecer um **Ăłtimo serviço**, mas tambĂ©m em apoiar um **framework robusto e prĂłspero**, o FastAPI. đ
-
-Por exemplo, vocĂȘ pode querer experimentar:
-
-* [Stainless](https://www.stainless.com/?utm_source=fastapi&utm_medium=referral)
-
-Algumas dessas soluçÔes tambĂ©m podem ser open source ou oferecer planos gratuitos, para que vocĂȘ possa testĂĄ-las sem compromisso financeiro. Outros geradores comerciais de SDK estĂŁo disponĂveis e podem ser encontrados online. đ€
-
## Crie um SDK em TypeScript { #create-a-typescript-sdk }
Vamos começar com uma aplicação FastAPI simples:
{* ../../docs_src/generate_clients/tutorial001_py310.py hl[7:9,12:13,16:17,21] *}
-Observe que as *operaçÔes de rota* definem os modelos que usam para o corpo da requisição e o corpo da resposta, usando os modelos `Item` e `ResponseMessage`.
+Observe que as *operaçÔes de rota* definem os modelos que usam para o payload da requisição e o payload da resposta, usando os modelos `Item` e `ResponseMessage`.
### Documentação da API { #api-docs }
<img src="/img/tutorial/generate-clients/image02.png">
-VocĂȘ tambĂ©m obterĂĄ preenchimento automĂĄtico para o corpo a ser enviado:
+VocĂȘ tambĂ©m obterĂĄ preenchimento automĂĄtico para o payload a enviar:
<img src="/img/tutorial/generate-clients/image03.png">
...isso ocorre porque o gerador de clientes usa o **ID de operação interno do OpenAPI** para cada *operação de rota*.
-O OpenAPI exige que cada ID de operação seja Ășnico em todas as *operaçÔes de rota*, entĂŁo o FastAPI usa o **nome da função**, o **path** e o **mĂ©todo HTTP** para gerar esse ID de operação, porque dessa forma ele pode garantir que os IDs de operação sejam Ășnicos.
+O OpenAPI exige que cada ID de operação seja Ășnico em todas as *operaçÔes de rota*, entĂŁo o FastAPI usa o **nome da função**, o **path** e o **mĂ©todo/operação HTTP** para gerar esse ID de operação, porque dessa forma ele pode garantir que os IDs de operação sejam Ășnicos.
Mas eu vou te mostrar como melhorar isso a seguir. đ€
Ao usar os clientes gerados automaticamente, vocĂȘ terĂĄ **preenchimento automĂĄtico** para:
* MĂ©todos.
-* Corpos de requisiçÔes, parùmetros de query, etc.
-* Corpos de respostas.
+* Payloads de requisiçÔes no body, parùmetros de query, etc.
+* Payloads de respostas.
VocĂȘ tambĂ©m terĂĄ **erros em linha** para tudo.
## Base64 vs Arquivos { #base64-vs-files }
-Primeiro, considere se vocĂȘ pode usar [Arquivos na request](../tutorial/request-files.md) para fazer upload de dados binĂĄrios e [Response personalizada - FileResponse](./custom-response.md#fileresponse--fileresponse-) para enviar dados binĂĄrios, em vez de codificĂĄ-los em JSON.
+Primeiro, considere se vocĂȘ pode usar [Arquivos na request](../tutorial/request-files.md) para fazer upload de dados binĂĄrios e [Response personalizada - FileResponse](./custom-response.md#fileresponse) para enviar dados binĂĄrios, em vez de codificĂĄ-los em JSON.
JSON sĂł pode conter strings codificadas em UTF-8, portanto nĂŁo pode conter bytes puros.
# Callbacks na OpenAPI { #openapi-callbacks }
-VocĂȘ poderia criar uma API com uma *operação de rota* que poderia acionar um request a uma *API externa* criada por outra pessoa (provavelmente o mesmo desenvolvedor que estaria *usando* sua API).
+VocĂȘ poderia criar uma API com uma *operação de rota* que poderia acionar um request para uma *API externa* criada por outra pessoa (provavelmente o mesmo desenvolvedor que estaria *usando* sua API).
O processo que acontece quando sua aplicação de API chama a *API externa* é chamado de "callback". Porque o software que o desenvolvedor externo escreveu envia um request para sua API e então sua API *chama de volta*, enviando um request para uma *API externa* (que provavelmente foi criada pelo mesmo desenvolvedor).
Nesse caso, vocĂȘ poderia querer documentar como essa API externa *deveria* ser. Que *operação de rota* ela deveria ter, que corpo ela deveria esperar, que resposta ela deveria retornar, etc.
-## Um aplicativo com callbacks { #an-app-with-callbacks }
+## Uma aplicação com callbacks { #an-app-with-callbacks }
Vamos ver tudo isso com um exemplo.
-Imagine que vocĂȘ desenvolve um aplicativo que permite criar faturas.
+Imagine que vocĂȘ desenvolve uma aplicação que permite criar faturas.
Essas faturas terĂŁo um `id`, `title` (opcional), `customer` e `total`.
* Enviar a notificação de volta para o usuårio da API (o desenvolvedor externo).
* Isso serĂĄ feito enviando um request POST (de *sua API*) para alguma *API externa* fornecida por esse desenvolvedor externo (este Ă© o "callback").
-## O aplicativo **FastAPI** normal { #the-normal-fastapi-app }
+## A aplicação **FastAPI** normal { #the-normal-fastapi-app }
-Vamos primeiro ver como o aplicativo da API normal se pareceria antes de adicionar o callback.
+Vamos primeiro ver como a aplicação da API normal se pareceria antes de adicionar o callback.
-Ele terå uma *operação de rota* que receberå um corpo `Invoice`, e um parùmetro de consulta `callback_url` que conterå a URL para o callback.
+Ela terå uma *operação de rota* que receberå um corpo `Invoice`, e um parùmetro de consulta `callback_url` que conterå a URL para o callback.
Essa parte Ă© bastante normal, a maior parte do cĂłdigo provavelmente jĂĄ Ă© familiar para vocĂȘ:
O código real do callback dependerå muito da sua própria aplicação de API.
-E provavelmente variarĂĄ muito de um aplicativo para o outro.
+E provavelmente variarå muito de uma aplicação para outra.
Poderia ser apenas uma ou duas linhas de cĂłdigo, como:
## Escreva o código de documentação do callback { #write-the-callback-documentation-code }
-Esse cĂłdigo nĂŁo serĂĄ executado em seu aplicativo, nĂłs sĂł precisamos dele para *documentar* como essa *API externa* deveria ser.
+Esse código não serå executado em sua aplicação, nós só precisamos dele para *documentar* como essa *API externa* deveria ser.
Mas, vocĂȘ jĂĄ sabe como criar facilmente documentação automĂĄtica para uma API com o **FastAPI**.
Hå 2 diferenças principais de uma *operação de rota* normal:
-* Ela não necessita ter nenhum código real, porque seu aplicativo nunca chamarå esse código. Ele é usado apenas para documentar a *API externa*. Então, a função poderia ter apenas `pass`.
+* Ela não necessita ter nenhum código real, porque sua aplicação nunca chamarå esse código. Ele é usado apenas para documentar a *API externa*. Então, a função poderia ter apenas `pass`.
* O *path* pode conter uma [expressĂŁo OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (veja mais abaixo) em que pode usar variĂĄveis com parĂąmetros e partes do request original enviado para *sua API*.
### A expressĂŁo do path do callback { #the-callback-path-expression }
///
-### Adicione o roteador de callback { #add-the-callback-router }
+### Adicione o router de callback { #add-the-callback-router }
-Nesse ponto vocĂȘ tem a(s) *operação(Ă”es) de rota de callback* necessĂĄria(s) (a(s) que o *desenvolvedor externo* deveria implementar na *API externa*) no roteador de callback que vocĂȘ criou acima.
+Nesse ponto vocĂȘ tem a(s) *operação(Ă”es) de rota de callback* necessĂĄria(s) (a(s) que o *desenvolvedor externo* deveria implementar na *API externa*) no router de callback que vocĂȘ criou acima.
-Agora use o parùmetro `callbacks` no decorador da *operação de rota da sua API* para passar o atributo `.routes` do roteador de callback:
+Agora use o parùmetro `callbacks` no decorador da *operação de rota da sua API* para passar o atributo `.routes` desse router de callback:
{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *}
/// tip | Dica
-Perceba que vocĂȘ nĂŁo estĂĄ passando o roteador em si (`invoices_callback_router`) para `callbacks=`, mas o atributo `.routes`, como em `invoices_callback_router.routes`. O FastAPI usarĂĄ essas rotas para gerar a documentação OpenAPI do callback.
+Perceba que vocĂȘ nĂŁo estĂĄ passando o router em si (`invoices_callback_router`) para `callbacks=`, mas seu `.routes`, como em `invoices_callback_router.routes`. FastAPI usarĂĄ essas rotas para gerar a documentação OpenAPI do callback.
///
### Verifique a documentação { #check-the-docs }
-Agora vocĂȘ pode iniciar seu aplicativo e ir para [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
+Agora vocĂȘ pode iniciar sua aplicação e ir para [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
VocĂȘ verĂĄ sua documentação incluindo uma seção "Callbacks" para sua *operação de rota* que mostra como a *API externa* deveria ser:
VocĂȘ pode declarar um parĂąmetro do tipo `Response` em sua *função de operação de rota* (assim como vocĂȘ pode fazer para cookies e headers).
-E entĂŁo vocĂȘ pode definir o `status_code` neste objeto de retorno *temporal*.
+E entĂŁo vocĂȘ pode definir o `status_code` neste objeto de retorno *temporĂĄrio*.
{* ../../docs_src/response_change_status_code/tutorial001_py310.py hl[1,9,12] *}
E se vocĂȘ declarar um `response_model`, ele ainda serĂĄ utilizado para filtrar e converter o objeto que vocĂȘ retornou.
-O **FastAPI** utilizarĂĄ este retorno *temporal* para extrair o cĂłdigo de status (e tambĂ©m cookies e headers), e irĂĄ colocĂĄ-los no retorno final que contĂ©m o valor que vocĂȘ retornou, filtrado por qualquer `response_model`.
+O **FastAPI** utilizarĂĄ este retorno *temporĂĄrio* para extrair o cĂłdigo de status (e tambĂ©m cookies e headers), e irĂĄ colocĂĄ-los no retorno final que contĂ©m o valor que vocĂȘ retornou, filtrado por qualquer `response_model`.
VocĂȘ tambĂ©m pode declarar o parĂąmetro `Response` nas dependĂȘncias, e definir o cĂłdigo de status nelas. Mas lembre-se que o Ășltimo que for definido Ă© o que prevalecerĂĄ.
Lembre-se de que se vocĂȘ retornar uma resposta diretamente em vez de usar o parĂąmetro `Response`, FastAPI a retornarĂĄ diretamente.
-Portanto, vocĂȘ terĂĄ que garantir que seus dados sejam do tipo correto. E.g. serĂĄ compatĂvel com JSON se vocĂȘ estiver retornando um `JSONResponse`.
+Portanto, vocĂȘ terĂĄ que garantir que seus dados sejam do tipo correto. Por exemplo, serĂĄ compatĂvel com JSON se vocĂȘ estiver retornando um `JSONResponse`.
E tambĂ©m que vocĂȘ nĂŁo esteja enviando nenhum dado que deveria ter sido filtrado por um `response_model`.
# Cabeçalhos de resposta { #response-headers }
+
## Use um parĂąmetro `Response` { #use-a-response-parameter }
VocĂȘ pode declarar um parĂąmetro do tipo `Response` na sua *função de operação de rota* (assim como vocĂȘ pode fazer para cookies).
VocĂȘ pode utilizar escopos do OAuth2 diretamente com o **FastAPI**, eles sĂŁo integrados para funcionar perfeitamente.
-Isso permitiria que vocĂȘ tivesse um sistema de permissionamento mais refinado, seguindo o padrĂŁo do OAuth2 integrado na sua aplicação OpenAPI (e as documentaçÔes da API).
+Isso permitiria que vocĂȘ tivesse um sistema de permissionamento mais refinado, seguindo o padrĂŁo OAuth2, integrado na sua aplicação OpenAPI (e a documentação da API).
-OAuth2 com escopos Ă© o mecanismo utilizado por muitos provedores de autenticação, como o Facebook, Google, GitHub, Microsoft, X (Twitter), etc. Eles utilizam isso para prover permissĂ”es especĂficas para os usuĂĄrios e aplicaçÔes.
+OAuth2 com escopos Ă© o mecanismo utilizado por muitos grandes provedores de autenticação, como o Facebook, Google, GitHub, Microsoft, X (Twitter), etc. Eles utilizam isso para prover permissĂ”es especĂficas para os usuĂĄrios e aplicaçÔes.
Toda vez que vocĂȘ "se autentica com" Facebook, Google, GitHub, Microsoft, X (Twitter), aquela aplicação estĂĄ utilizando o OAuth2 com escopos.
Estes escopos representam "permissÔes".
-No OpenAPI (e.g. os documentos da API), vocĂȘ pode definir "esquemas de segurança".
+No OpenAPI (por exemplo, a documentação da API), vocĂȘ pode definir "esquemas de segurança".
Quando um desses esquemas de segurança utiliza OAuth2, vocĂȘ pode tambĂ©m declarar e utilizar escopos.
Eles sĂŁo normalmente utilizados para declarar permissĂ”es de segurança especĂficas, como por exemplo:
-* `users:read` or `users:write` sĂŁo exemplos comuns.
+* `users:read` ou `users:write` sĂŁo exemplos comuns.
* `instagram_basic` Ă© utilizado pelo Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` Ă© utilizado pelo Google.
## VisĂŁo global { #global-view }
-Primeiro, vamos olhar rapidamente as partes que mudam dos exemplos do **Tutorial - Guia de UsuĂĄrio** para [OAuth2 com Senha (e hash), Bearer com tokens JWT](../../tutorial/security/oauth2-jwt.md). Agora utilizando escopos OAuth2:
+Primeiro, vamos olhar rapidamente as partes que mudam dos exemplos no **Tutorial - Guia de UsuĂĄrio** principal para [OAuth2 com Senha (e hash), Bearer com tokens JWT](../../tutorial/security/oauth2-jwt.md). Agora utilizando escopos OAuth2:
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *}
{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}
-Pelo motivo de estarmos declarando estes escopos, eles aparecerĂŁo nos documentos da API quando vocĂȘ se autenticar/autorizar.
+Pelo motivo de estarmos declarando estes escopos, eles aparecerĂŁo na documentação da API quando vocĂȘ se autenticar/autorizar.
E vocĂȘ poderĂĄ selecionar quais escopos vocĂȘ deseja dar acesso: `me` e `items`.
VocĂȘ pode utilizar `Security` para declarar dependĂȘncias (assim como `Depends`), porĂ©m o `Security` tambĂ©m recebe o parĂąmetro `scopes` com uma lista de escopos (strings).
-Neste caso, nĂłs passamos a função `get_current_active_user` como dependĂȘncia para `Security` (da mesma forma que nĂłs farĂamos com `Depends`).
+Neste caso, nĂłs passamos a função de dependĂȘncia `get_current_active_user` para `Security` (da mesma forma que nĂłs farĂamos com `Depends`).
Mas nós também passamos uma `list` de escopos, neste caso com apenas um escopo: `items` (poderia ter mais).
Este Ă© o usado pelas dependĂȘncias acima.
-Aqui Ă© onde estamos utilizando o mesmo esquema OAuth2 que nĂłs declaramos antes, declarando-o como uma dependĂȘncia: `oauth2_scheme`.
+Aqui Ă© onde estamos utilizando o mesmo esquema OAuth2 que nĂłs criamos antes, declarando-o como uma dependĂȘncia: `oauth2_scheme`.
Porque esta função de dependĂȘncia nĂŁo possui nenhum requerimento de escopo, nĂłs podemos utilizar `Depends` com o `oauth2_scheme`. NĂłs nĂŁo precisamos utilizar `Security` quando nĂłs nĂŁo precisamos especificar escopos de segurança.
## Verifique { #check-it }
-Se vocĂȘ abrir os documentos da API, vocĂȘ pode autenticar e especificar quais escopos vocĂȘ quer autorizar.
+Se vocĂȘ abrir a documentação da API, vocĂȘ pode autenticar e especificar quais escopos vocĂȘ quer autorizar.
<img src="/img/tutorial/security/image11.png">
Neste exemplo nĂłs estamos utilizando o fluxo de senha do OAuth2.
-Isso é apropriado quando nós estamos autenticando em nossa própria aplicação, provavelmente com o nosso próprio "*frontend*".
+Isso é apropriado quando nós estamos autenticando em nossa própria aplicação, provavelmente com o nosso próprio frontend.
Porque nĂłs podemos confiar nele para receber o `username` e o `password`, pois nĂłs controlamos isso.
-Mas se nĂłs estamos construindo uma aplicação OAuth2 que outros poderiam conectar (i.e., se vocĂȘ estĂĄ construindo um provedor de autenticação equivalente ao Facebook, Google, GitHub, etc.) vocĂȘ deveria utilizar um dos outros fluxos.
+Mas se nĂłs estamos construindo uma aplicação OAuth2 que outros poderiam conectar (ou seja, se vocĂȘ estĂĄ construindo um provedor de autenticação equivalente ao Facebook, Google, GitHub, etc.) vocĂȘ deveria utilizar um dos outros fluxos.
O mais comum Ă© o fluxo implĂcito.
# ConfiguraçÔes e Variåveis de Ambiente { #settings-and-environment-variables }
+
Em muitos casos, sua aplicação pode precisar de configuraçÔes externas, por exemplo chaves secretas, credenciais de banco de dados, credenciais para serviços de e-mail, etc.
A maioria dessas configuraçÔes Ă© variĂĄvel (pode mudar), como URLs de banco de dados. E muitas podem ser sensĂveis, como segredos.
Se vocĂȘ quer transmitir dados que podem ser estruturados como JSON, vocĂȘ deveria [Transmitir JSON Lines](../tutorial/stream-json-lines.md).
-Mas se vocĂȘ quer transmitir dados binĂĄrios puros ou strings, veja como fazer.
+Mas se vocĂȘ quer **transmitir dados binĂĄrios puros** ou strings, veja como fazer.
/// note | Nota
## Casos de uso { #use-cases }
-VocĂȘ pode usar isto para transmitir strings puras, por exemplo diretamente da saĂda de um serviço de AI LLM.
+VocĂȘ pode usar isto para transmitir strings puras, por exemplo diretamente da saĂda de um serviço de **AI LLM**.
-VocĂȘ tambĂ©m pode usĂĄ-lo para transmitir arquivos binĂĄrios grandes, enviando cada bloco de dados Ă medida que o lĂȘ, sem precisar carregar tudo na memĂłria de uma vez.
+VocĂȘ tambĂ©m pode usĂĄ-lo para transmitir **arquivos binĂĄrios grandes**, enviando cada bloco de dados Ă medida que o lĂȘ, sem precisar carregar tudo na memĂłria de uma vez.
-VocĂȘ tambĂ©m pode transmitir vĂdeo ou ĂĄudio desta forma; pode atĂ© ser gerado enquanto vocĂȘ processa e envia.
+VocĂȘ tambĂ©m pode transmitir **vĂdeo** ou **ĂĄudio** desta forma; pode atĂ© ser gerado enquanto vocĂȘ processa e envia.
## Um `StreamingResponse` com `yield` { #a-streamingresponse-with-yield }
-Se vocĂȘ declarar `response_class=StreamingResponse` na sua função de operação de rota, vocĂȘ pode usar `yield` para enviar cada bloco de dados em sequĂȘncia.
+Se vocĂȘ declarar `response_class=StreamingResponse` na sua *função de operação de rota*, vocĂȘ pode usar `yield` para enviar cada bloco de dados em sequĂȘncia.
{* ../../docs_src/stream_data/tutorial001_py310.py ln[1:23] hl[20,23] *}
{* ../../docs_src/stream_data/tutorial001_py310.py ln[32:35] hl[33] *}
-Isso tambĂ©m significa que, com `StreamingResponse`, vocĂȘ tem a liberdade e a responsabilidade de produzir e codificar os bytes exatamente como precisam ser enviados, independentemente das anotaçÔes de tipo. đ€
+Isso tambĂ©m significa que, com `StreamingResponse`, vocĂȘ tem a **liberdade** e a **responsabilidade** de produzir e codificar os bytes exatamente como precisam ser enviados, independentemente das anotaçÔes de tipo. đ€
### Transmitir bytes { #stream-bytes }
## Um `PNGStreamingResponse` personalizado { #a-custom-pngstreamingresponse }
-Nos exemplos acima, os bytes eram transmitidos, mas a resposta não tinha um cabeçalho `Content-Type`, então o cliente não sabia que tipo de dado estava recebendo.
+Nos exemplos acima, os bytes eram transmitidos, mas a response não tinha um cabeçalho `Content-Type`, então o cliente não sabia que tipo de dado estava recebendo.
VocĂȘ pode criar uma subclasse personalizada de `StreamingResponse` que define o cabeçalho `Content-Type` para o tipo de dado que vocĂȘ estĂĄ transmitindo.
{* ../../docs_src/stream_data/tutorial002_py310.py ln[6,19:20] hl[20] *}
-Em seguida, vocĂȘ pode usar essa nova classe em `response_class=PNGStreamingResponse` na sua função de operação de rota:
+Em seguida, vocĂȘ pode usar essa nova classe em `response_class=PNGStreamingResponse` na sua *função de operação de rota*:
{* ../../docs_src/stream_data/tutorial002_py310.py ln[23:27] hl[23] *}
///
-Ao usar um bloco `with`, garantimos que o objeto semelhante a arquivo seja fechado após a função geradora (a função com `yield`) terminar. Ou seja, após terminar de enviar a resposta.
+Ao usar um bloco `with`, garantimos que o objeto semelhante a arquivo seja fechado após a função geradora (a função com `yield`) terminar. Ou seja, após terminar de enviar a response.
Isso nĂŁo seria tĂŁo importante neste exemplo especĂfico porque Ă© um arquivo falso em memĂłria (com `io.BytesIO`), mas com um arquivo real, seria importante garantir que o arquivo fosse fechado ao final do trabalho.
///
-Para evitar bloquear o loop de eventos, vocĂȘ pode simplesmente declarar a função de operação de rota com `def` normal em vez de `async def`. Assim, o FastAPI a executarĂĄ em um worker de threadpool, evitando bloquear o loop principal.
+Para evitar bloquear o loop de eventos, vocĂȘ pode simplesmente declarar a *função de operação de rota* com `def` normal em vez de `async def`. Assim, o FastAPI a executarĂĄ em um worker de threadpool, evitando bloquear o loop principal.
{* ../../docs_src/stream_data/tutorial002_py310.py ln[30:34] hl[31] *}
# Adicionando WSGI - Flask, Django, entre outros { #including-wsgi-flask-django-others }
+
Como vocĂȘ viu em [SubaplicaçÔes - Montagens](sub-applications.md) e [AtrĂĄs de um Proxy](behind-a-proxy.md), vocĂȘ pode montar aplicaçÔes WSGI.
Para isso, vocĂȘ pode utilizar o `WSGIMiddleware` para encapsular a sua aplicação WSGI, como por exemplo Flask, Django, etc.
Ă o framework Python mais popular e amplamente confiĂĄvel. Ă utilizado para construir sistemas como o Instagram.
-Ă relativamente bem acoplado com bancos de dados relacionais (como MySQL ou PostgreSQL), entĂŁo, ter um banco de dados NoSQL (como Couchbase, MongoDB, Cassandra, etc.) como mecanismo principal de armazenamento nĂŁo Ă© muito fĂĄcil.
+Ă relativamente fortemente acoplado com bancos de dados relacionais (como MySQL ou PostgreSQL), entĂŁo, ter um banco de dados NoSQL (como Couchbase, MongoDB, Cassandra, etc.) como mecanismo principal de armazenamento nĂŁo Ă© muito fĂĄcil.
Foi criado para gerar o HTML no backend, nĂŁo para criar APIs usadas por um frontend moderno (como React, Vue.js e Angular) ou por outros sistemas (como dispositivos <abbr title="Internet of Things - Internet das Coisas">IoT</abbr>) comunicando com ele.
### [Django REST Framework](https://www.django-rest-framework.org/) { #django-rest-framework }
-Django REST framework foi criado para ser uma caixa de ferramentas flexĂvel para construção de APIs Web utilizando Django por baixo, para melhorar suas capacidades de API.
+Django REST Framework foi criado para ser uma caixa de ferramentas flexĂvel para construção de APIs Web utilizando Django por baixo, para melhorar suas capacidades de API.
Ele Ă© utilizado por muitas empresas incluindo Mozilla, Red Hat e Eventbrite.
response = requests.get("http://example.com/some/url")
```
-A contra-parte na aplicação FastAPI, a operação de rota, poderia ficar assim:
+A *operação de rota* da API equivalente no FastAPI poderia ficar assim:
```Python hl_lines="1"
@app.get("/some/url")
/// note | Nota
-APIStar foi criado por Tom Christie. O mesmo cara que criou:
+APIStar foi criado por Tom Christie. A mesma pessoa que criou:
* Django REST Framework
* Starlette (no qual **FastAPI** Ă© baseado)
---
-Se vocĂȘ simplesmente nĂŁo sabe, use apenas `def`.
+Se vocĂȘ simplesmente nĂŁo sabe, use `def` normal.
---
-**Note**: VocĂȘ pode misturar `def` e `async def` nas suas *funçÔes de operação de rota* tanto quanto necessĂĄrio e definir cada função usando a melhor opção para vocĂȘ. FastAPI irĂĄ fazer a coisa certa com elas.
+**Nota**: VocĂȘ pode misturar `def` e `async def` nas suas *funçÔes de operação de rota* tanto quanto necessĂĄrio e definir cada função usando a melhor opção para vocĂȘ. FastAPI irĂĄ fazer a coisa certa com elas.
De qualquer forma, em ambos os casos acima, FastAPI irĂĄ trabalhar assincronamente e ser extremamente rĂĄpido.
* conteĂșdo que seu programa deu ao sistema para ser escrito no disco
* uma operação em uma API remota
* uma operação no banco de dados finalizar
-* uma solicitação no banco de dados retornar o resultado
+* uma consulta ao banco de dados retornar os resultados
* etc.
-
Quanto o tempo de execução Ă© consumido majoritariamente pela espera de operaçÔes <abbr title="Input and Output - Entrada e SaĂda">I/O</abbr>, essas operaçÔes sĂŁo chamadas operaçÔes "limitadas por I/O".
+
Como o tempo de execução Ă© consumido majoritariamente pela espera de operaçÔes <abbr title="Input and Output - Entrada e SaĂda">I/O</abbr>, essas operaçÔes sĂŁo chamadas operaçÔes "limitadas por I/O".
Isso Ă© chamado de "assĂncrono" porque o computador / programa nĂŁo tem que ser "sincronizado" com a tarefa lenta, esperando pelo momento exato em que a tarefa finaliza, enquanto nĂŁo faz nada, para ser capaz de pegar o resultado da tarefa e dar continuidade ao trabalho.
<img src="/img/async/concurrent-burgers/concurrent-burgers-01.png" class="illustration">
-EntĂŁo chega a sua vez, vocĂȘ pede dois saborosos hambĂșrgueres para vocĂȘ e seu _crush_. đđ
+EntĂŁo chega a sua vez, vocĂȘ pede dois saborosos hambĂșrgueres para vocĂȘ e seu _crush_. đđ
<img src="/img/async/concurrent-burgers/concurrent-burgers-02.png" class="illustration">
Como vocĂȘ e seu _crush_ estĂŁo ocupados nĂŁo permitindo que ninguĂ©m passe na frente e pegue seus hambĂșrgueres assim que estiverem prontos, vocĂȘ nĂŁo pode dar atenção ao seu _crush_. đ
-Isso Ă© trabalho "sĂncrono", vocĂȘ estĂĄ "sincronizado" com o caixa / cozinheiro đšâđł. VocĂȘ tem que esperar đ e estar lĂĄ no exato momento que o caixa / cozinheiro đšâđł terminar os hambĂșrgueres e os der a vocĂȘ, ou entĂŁo, outro alguĂ©m pode pegĂĄ-los.
+Isso Ă© trabalho "sĂncrono", vocĂȘ estĂĄ "sincronizado" com o caixa/cozinheiro đšâđł. VocĂȘ tem que esperar đ e estar lĂĄ no exato momento que o caixa/cozinheiro đšâđł terminar os hambĂșrgueres e os der a vocĂȘ, ou entĂŁo, outro alguĂ©m pode pegĂĄ-los.
<img src="/img/async/parallel-burgers/parallel-burgers-04.png" class="illustration">
-EntĂŁo seu caixa / cozinheiro đšâđł finalmente volta com seus hambĂșrgueres, depois de um longo tempo esperando đ por eles em frente ao balcĂŁo.
+EntĂŁo seu caixa/cozinheiro đšâđł finalmente volta com seus hambĂșrgueres, depois de um longo tempo esperando đ por eles em frente ao balcĂŁo.
<img src="/img/async/parallel-burgers/parallel-burgers-05.png" class="illustration">
VocĂȘ pega seus hambĂșrgueres e vai para a mesa com seu _crush_.
-VocĂȘs comem os hambĂșrgueres, e o trabalho estĂĄ terminado. âč
+VocĂȘs apenas os comem, e o trabalho estĂĄ terminado. âč
<img src="/img/async/parallel-burgers/parallel-burgers-06.png" class="illustration">
---
-Nesse cenĂĄrio dos hambĂșrgueres paralelos, vocĂȘ Ă© um computador / programa đ€ com dois processadores (vocĂȘ e seu _crush_), ambos esperando đ e dedicando sua atenção ⯠"esperando no balcĂŁo" đ por um bom tempo.
+Nesse cenĂĄrio dos hambĂșrgueres paralelos, vocĂȘ Ă© um computador / programa đ€ com dois processadores (vocĂȘ e seu _crush_), ambos esperando đ e dedicando sua atenção ⯠a "esperar no balcĂŁo" đ por um bom tempo.
-A lanchonete paralela tem 8 processadores (caixas / cozinheiros), enquanto a lanchonete dos hambĂșrgueres concorrentes tinha apenas 2 (um caixa e um cozinheiro).
+A lanchonete tem 8 processadores (caixas/cozinheiros). Enquanto a lanchonete dos hambĂșrgueres concorrentes poderia ter apenas 2 (um caixa e um cozinheiro).
Ainda assim, a experiĂȘncia final nĂŁo foi a melhor. đ
---
-Essa seria o equivalente paralelo Ă histĂłria dos hambĂșrgueres. đ
+Essa seria a histĂłria equivalente paralela para hambĂșrgueres. đ
Para um exemplo "mais real", imagine um banco.
E vocĂȘ tinha que esperar đ na fila por um longo tempo ou poderia perder a vez.
-VocĂȘ provavelmente nĂŁo gostaria de levar seu _crush_ đ com vocĂȘ para um rolezinho no banco đŠ.
+VocĂȘ provavelmente nĂŁo gostaria de levar seu _crush_ đ com vocĂȘ para resolver assuntos no banco đŠ.
### ConclusĂŁo dos hambĂșrgueres { #burger-conclusion }
-Nesse cenĂĄrio dos "hambĂșrgueres com seu _crush_", como tem muita espera, faz mais sentido ter um sistema concorrente âžđâŻ.
+Nesse cenĂĄrio dos "hambĂșrgueres de fast food com seu _crush_", como tem muita espera đ, faz mais sentido ter um sistema concorrente âžđâŻ.
Esse é o caso da maioria das aplicaçÔes web.
-Muitos, muitos usuĂĄrios, mas seu servidor estĂĄ esperando đ pela sua conexĂŁo nĂŁo tĂŁo boa enviar suas requisiçÔes.
+Muitos, muitos usuĂĄrios, mas seu servidor estĂĄ esperando đ pela conexĂŁo nĂŁo tĂŁo boa deles enviar suas requisiçÔes.
E entĂŁo esperando đ novamente as respostas voltarem.
NĂŁo hĂĄ espera đ em lugar algum, apenas um monte de trabalho para ser feito, em mĂșltiplos cĂŽmodos da casa.
-VocĂȘ poderia ter turnos como no exemplo dos hambĂșrgueres, primeiro a sala de estar, entĂŁo a cozinha, mas como vocĂȘ nĂŁo estĂĄ esperando por nada, apenas limpando e limpando, as chamadas nĂŁo afetariam em nada.
+VocĂȘ poderia ter turnos como no exemplo dos hambĂșrgueres, primeiro a sala de estar, entĂŁo a cozinha, mas como vocĂȘ nĂŁo estĂĄ esperando đ por nada, apenas limpando e limpando, as chamadas nĂŁo afetariam em nada.
Levaria o mesmo tempo para finalizar com ou sem turnos (concorrĂȘncia) e vocĂȘ teria feito o mesmo tanto de trabalho.
-Mas nesse caso, se vocĂȘ trouxesse os 8 ex-caixas / cozinheiros / agora-faxineiros, e cada um deles (mais vocĂȘ) pudessem dividir a casa para limpĂĄ-la, vocĂȘs fariam toda a limpeza em **paralelo**, com a ajuda extra, e terminariam muito mais cedo.
+Mas nesse caso, se vocĂȘ trouxesse os 8 ex-caixas/cozinheiros/agora-faxineiros, e cada um deles (mais vocĂȘ) pudessem dividir a casa para limpĂĄ-la, vocĂȘs fariam toda a limpeza em **paralelo**, com a ajuda extra, e terminariam muito mais cedo.
Nesse cenĂĄrio, cada um dos faxineiros (incluindo vocĂȘ) poderia ser um processador, fazendo a sua parte do trabalho.
Por exemplo:
-* **Processamento de ĂĄudio** ou **imagem**
-* **Visão Computacional**: uma imagem é composta por milhÔes de pixels, cada pixel tem 3 valores / cores, processar isso normalmente exige alguma computação em todos esses pixels ao mesmo tempo
-* **Aprendizado de MĂĄquina**: Normalmente exige muita multiplicação de matrizes e vetores. Pense numa grande planilha com nĂșmeros e em multiplicar todos eles juntos e ao mesmo tempo.
-* **Deep Learning**: Esse Ă© um subcampo do Aprendizado de MĂĄquina, entĂŁo, o mesmo se aplica. A diferença Ă© que nĂŁo hĂĄ apenas uma grande planilha com nĂșmeros para multiplicar, mas um grande conjunto delas, e em muitos casos, vocĂȘ utiliza um processador especial para construir e/ou usar esses modelos.
+* **Processamento de ĂĄudio** ou **imagem**.
+* **Visão Computacional**: uma imagem é composta por milhÔes de pixels, cada pixel tem 3 valores / cores, processar isso normalmente exige alguma computação nesses pixels, todos ao mesmo tempo.
+* **Aprendizado de MĂĄquina**: normalmente exige muita multiplicação de "matrizes" e "vetores". Pense numa grande planilha com nĂșmeros e em multiplicar todos eles juntos e ao mesmo tempo.
+* **Deep Learning**: esse Ă© um subcampo do Aprendizado de MĂĄquina, entĂŁo, o mesmo se aplica. A diferença Ă© que nĂŁo hĂĄ apenas uma planilha com nĂșmeros para multiplicar, mas um grande conjunto delas, e em muitos casos, vocĂȘ utiliza um processador especial para construir e / ou usar esses modelos.
### ConcorrĂȘncia + Paralelismo: Web + Aprendizado de MĂĄquina { #concurrency-parallelism-web-machine-learning }
Com **FastAPI** vocĂȘ pode levar a vantagem da concorrĂȘncia que Ă© muito comum para desenvolvimento web (o mesmo atrativo de NodeJS).
-Mas vocĂȘ tambĂ©m pode explorar os benefĂcios do paralelismo e multiprocessamento (tendo mĂșltiplos processadores rodando em paralelo) para trabalhos **limitados por CPU** como aqueles em sistemas de Aprendizado de MĂĄquina.
+Mas vocĂȘ tambĂ©m pode explorar os benefĂcios do paralelismo e multiprocessamento (tendo mĂșltiplos processos rodando em paralelo) para trabalhos **limitados por CPU** como aqueles em sistemas de Aprendizado de MĂĄquina.
-Isso, somado ao simples fato que Python é a principal linguagem para **Data Science**, Aprendizado de Måquina e especialmente Deep Learning, faz do FastAPI uma ótima escolha para APIs web e aplicaçÔes com Data Science / Aprendizado de Måquina (entre muitas outras).
+Isso, somado ao simples fato que Python é a principal linguagem para **Data Science**, Aprendizado de Måquina e especialmente Deep Learning, faz do FastAPI uma ótima escolha para APIs web e aplicaçÔes de Data Science / Aprendizado de Måquina (entre muitas outras).
Para ver como alcançar esse paralelismo em produção veja a seção sobre [Implantação](deployment/index.md).
---
-EntĂŁo, se vocĂȘ estĂĄ usando uma biblioteca que diz que vocĂȘ pode chamĂĄ-la com `await`, vocĂȘ precisa criar as *funçÔes de operação de rota* com `async def`, como em:
+EntĂŁo, se vocĂȘ estĂĄ usando uma biblioteca que diz que vocĂȘ pode chamĂĄ-la com `await`, vocĂȘ precisa criar as *funçÔes de operação de rota* que a utilizam com `async def`, como em:
```Python hl_lines="2-3"
@app.get('/burgers')
Mas ao mesmo tempo, funçÔes definidas com `async def` tĂȘm que ser "aguardadas". EntĂŁo, funçÔes com `async def` podem ser chamadas somente dentro de funçÔes definidas com `async def` tambĂ©m.
-EntĂŁo, sobre o ovo e a galinha, como vocĂȘ chama a primeira função async?
+EntĂŁo, sobre o ovo e a galinha, como vocĂȘ chama a primeira função `async`?
-Se vocĂȘ estivar trabalhando com **FastAPI** nĂŁo terĂĄ que se preocupar com isso, porquĂȘ essa "primeira" função serĂĄ a sua *função de operação de rota*, e o FastAPI saberĂĄ como fazer a coisa certa.
+Se vocĂȘ estiver trabalhando com **FastAPI** nĂŁo terĂĄ que se preocupar com isso, porquĂȘ essa "primeira" função serĂĄ a sua *função de operação de rota*, e o FastAPI saberĂĄ como fazer a coisa certa.
Mas se vocĂȘ quiser usar `async` / `await` sem FastAPI, vocĂȘ tambĂ©m pode fazĂȘ-lo.
### DependĂȘncias { #dependencies }
-O mesmo se aplica para as [dependĂȘncias](tutorial/dependencies/index.md). Se uma dependĂȘncia tem as funçÔes com padrĂŁo `def` ao invĂ©s de `async def`, ela Ă© rodada no threadpool externo.
+O mesmo se aplica para as [dependĂȘncias](tutorial/dependencies/index.md). Se uma dependĂȘncia Ă© uma função `def` padrĂŁo ao invĂ©s de `async def`, ela Ă© rodada no threadpool externo.
### Sub-dependĂȘncias { #sub-dependencies }
Isso estĂĄ em contraste Ă s funçÔes que o FastAPI chama para vocĂȘ: *funçÔes de operação de rota* e dependĂȘncias.
-Se sua função de utilidade Ă© uma função normal com `def`, ela serĂĄ chamada diretamente (como vocĂȘ a escreve no cĂłdigo), nĂŁo em uma threadpool, se a função Ă© criada com `async def` entĂŁo vocĂȘ deve esperar por essa função quando vocĂȘ chamĂĄ-la no seu cĂłdigo.
+Se sua função de utilidade Ă© uma função normal com `def`, ela serĂĄ chamada diretamente (como vocĂȘ a escreve no cĂłdigo), nĂŁo em uma threadpool, se a função Ă© criada com `async def` entĂŁo vocĂȘ deveria usar `await` nessa função quando vocĂȘ chamĂĄ-la no seu cĂłdigo.
---
## Provedores de Nuvem - Patrocinadores { #cloud-providers-sponsors }
-Alguns outros provedores de nuvem âš [**patrocinam o FastAPI**](../help-fastapi.md#sponsor-the-author) âš tambĂ©m. đ
+Alguns outros provedores de nuvem âš [**patrocinam o FastAPI**](https://github.com/sponsors/tiangolo) âš tambĂ©m. đ
VocĂȘ tambĂ©m pode considerĂĄ-los para seguir seus tutoriais e experimentar seus serviços:
# Conceitos de ImplantaçÔes { #deployments-concepts }
-Ao implantar um aplicativo **FastAPI**, ou na verdade, qualquer tipo de API da web, hĂĄ vĂĄrios conceitos com os quais vocĂȘ provavelmente se importa e, usando-os, vocĂȘ pode encontrar a maneira **mais apropriada** de **implantar seu aplicativo**.
+Ao implantar uma aplicação **FastAPI**, ou na verdade, qualquer tipo de API da web, hĂĄ vĂĄrios conceitos com os quais vocĂȘ provavelmente se importa e, usando-os, vocĂȘ pode encontrar a maneira **mais apropriada** de **implantar sua aplicação**.
Alguns dos conceitos importantes sĂŁo:
Ao considerar esses conceitos, vocĂȘ serĂĄ capaz de **avaliar e projetar** a melhor maneira de implantar **suas prĂłprias APIs**.
-Nos prĂłximos capĂtulos, darei a vocĂȘ mais **receitas concretas** para implantar aplicativos FastAPI.
+Nos prĂłximos capĂtulos, darei a vocĂȘ mais **receitas concretas** para implantar aplicaçÔes FastAPI.
Mas por enquanto, vamos verificar essas importantes **ideias conceituais**. Esses conceitos tambĂ©m se aplicam a qualquer outro tipo de API da web. đĄ
No [capĂtulo anterior sobre HTTPS](https.md) aprendemos como o HTTPS fornece criptografia para sua API.
-Também vimos que o HTTPS normalmente é fornecido por um componente **externo** ao seu servidor de aplicativos, um **Proxy de terminação TLS**.
+Também vimos que o HTTPS normalmente é fornecido por um componente **externo** ao seu servidor de aplicaçÔes, um **Proxy de terminação TLS**.
E tem que haver algo responsĂĄvel por **renovar os certificados HTTPS**, pode ser o mesmo componente ou pode ser algo diferente.
* Isso nĂŁo se refere ao arquivo, nem ao cĂłdigo, refere-se **especificamente** Ă coisa que estĂĄ sendo **executada** e gerenciada pelo sistema operacional.
* Qualquer programa, qualquer código, **só pode fazer coisas** quando estå sendo **executado**. Então, quando hå um **processo em execução**.
* O processo pode ser **terminado** (ou "morto") por vocĂȘ, ou pelo sistema operacional. Nesse ponto, ele para de rodar/ser executado, e ele **nĂŁo pode mais fazer coisas**.
-* Cada aplicativo que vocĂȘ tem em execução no seu computador tem algum processo por trĂĄs dele, cada programa em execução, cada janela, etc. E normalmente hĂĄ muitos processos em execução **ao mesmo tempo** enquanto um computador estĂĄ ligado.
+* Cada aplicação que vocĂȘ tem em execução no seu computador tem algum processo por trĂĄs dela, cada programa em execução, cada janela, etc. E normalmente hĂĄ muitos processos em execução **ao mesmo tempo** enquanto um computador estĂĄ ligado.
* Pode haver **vårios processos** do **mesmo programa** em execução ao mesmo tempo.
Se vocĂȘ verificar o "gerenciador de tarefas" ou o "monitor do sistema" (ou ferramentas semelhantes) no seu sistema operacional, poderĂĄ ver muitos desses processos em execução.
### Executar automaticamente na inicialização { #run-automatically-on-startup }
-Em geral, vocĂȘ provavelmente desejarĂĄ que o programa do servidor (por exemplo, Uvicorn) seja iniciado automaticamente na inicialização do servidor e, sem precisar de nenhuma **intervenção humana**, tenha um processo sempre em execução com sua API (por exemplo, Uvicorn executando seu aplicativo FastAPI).
+Em geral, vocĂȘ provavelmente desejarĂĄ que o programa do servidor (por exemplo, Uvicorn) seja iniciado automaticamente na inicialização do servidor e, sem precisar de nenhuma **intervenção humana**, tenha um processo sempre em execução com sua API (por exemplo, Uvicorn executando sua aplicação FastAPI).
### Programa separado { #separate-program }
-Para conseguir isso, vocĂȘ normalmente terĂĄ um **programa separado** que garantiria que seu aplicativo fosse executado na inicialização. E em muitos casos, ele tambĂ©m garantiria que outros componentes ou aplicativos tambĂ©m fossem executados, por exemplo, um banco de dados.
+Para conseguir isso, vocĂȘ normalmente terĂĄ um **programa separado** que garantiria que sua aplicação fosse executada na inicialização. E em muitos casos, ele tambĂ©m garantiria que outros componentes ou aplicaçÔes tambĂ©m fossem executados, por exemplo, um banco de dados.
### Ferramentas de exemplo para executar na inicialização { #example-tools-to-run-at-startup }
## ReinicializaçÔes { #restarts }
-Semelhante a garantir que seu aplicativo seja executado na inicialização, vocĂȘ provavelmente tambĂ©m deseja garantir que ele seja **reiniciado** apĂłs falhas.
+Semelhante a garantir que sua aplicação seja executada na inicialização, vocĂȘ provavelmente tambĂ©m deseja garantir que ela seja **reiniciada** apĂłs falhas.
### NĂłs cometemos erros { #we-make-mistakes }
### Pequenos erros sĂŁo tratados automaticamente { #small-errors-automatically-handled }
-Ao criar APIs da web com FastAPI, se houver um erro em nosso cĂłdigo, o FastAPI normalmente o conterĂĄ na Ășnica solicitação que acionou o erro. đĄ
+Ao criar APIs da web com FastAPI, se houver um erro em nosso cĂłdigo, o FastAPI normalmente o conterĂĄ na Ășnica request que acionou o erro. đĄ
-O cliente receberå um **Erro Interno do Servidor 500** para essa solicitação, mas o aplicativo continuarå funcionando para as próximas solicitaçÔes em vez de travar completamente.
+O cliente receberå um **Erro Interno do Servidor 500** para essa request, mas a aplicação continuarå funcionando para as próximas requests em vez de travar completamente.
### Erros maiores - Travamentos { #bigger-errors-crashes }
-No entanto, pode haver casos em que escrevemos algum cĂłdigo que **trava todo o aplicativo**, fazendo com que o Uvicorn e o Python travem. đ„
+No entanto, pode haver casos em que escrevemos algum cĂłdigo que **trava toda a aplicação**, fazendo com que o Uvicorn e o Python travem. đ„
-E ainda assim, vocĂȘ provavelmente nĂŁo gostaria que o aplicativo permanecesse inativo porque houve um erro em um lugar, vocĂȘ provavelmente quer que ele **continue em execução** pelo menos para as *operaçÔes de rota* que nĂŁo estĂŁo quebradas.
+E ainda assim, vocĂȘ provavelmente nĂŁo gostaria que a aplicação permanecesse inativa porque houve um erro em um lugar, vocĂȘ provavelmente quer que ela **continue em execução** pelo menos para as *operaçÔes de rota* que nĂŁo estĂŁo quebradas.
### Reiniciar apĂłs falha { #restart-after-crash }
/// tip | Dica
-...Embora se o aplicativo inteiro estiver **travando imediatamente**, provavelmente nĂŁo faça sentido reiniciĂĄ-lo para sempre. Mas nesses casos, vocĂȘ provavelmente notarĂĄ isso durante o desenvolvimento, ou pelo menos logo apĂłs a implantação.
+...Embora se a aplicação inteira estiver **travando imediatamente**, provavelmente nĂŁo faça sentido reiniciĂĄ-la para sempre. Mas nesses casos, vocĂȘ provavelmente notarĂĄ isso durante o desenvolvimento, ou pelo menos logo apĂłs a implantação.
-EntĂŁo, vamos nos concentrar nos casos principais, onde ele pode travar completamente em alguns casos especĂficos **no futuro**, e ainda faz sentido reiniciĂĄ-lo.
+EntĂŁo, vamos nos concentrar nos casos principais, onde ela pode travar completamente em alguns casos especĂficos **no futuro**, e ainda faz sentido reiniciĂĄ-la.
///
-VocĂȘ provavelmente gostaria de ter a coisa responsĂĄvel por reiniciar seu aplicativo como um **componente externo**, porque a essa altura, o mesmo aplicativo com Uvicorn e Python jĂĄ havia travado, entĂŁo nĂŁo hĂĄ nada no mesmo cĂłdigo do mesmo aplicativo que possa fazer algo a respeito.
+VocĂȘ provavelmente gostaria de ter a coisa responsĂĄvel por reiniciar sua aplicação como um **componente externo**, porque a essa altura, a mesma aplicação com Uvicorn e Python jĂĄ havia travado, entĂŁo nĂŁo hĂĄ nada no mesmo cĂłdigo da mesma aplicação que possa fazer algo a respeito.
### Ferramentas de exemplo para reiniciar automaticamente { #example-tools-to-restart-automatically }
## Replicação - Processos e Memória { #replication-processes-and-memory }
-Com um aplicativo FastAPI, usando um programa de servidor como o comando `fastapi` que executa o Uvicorn, executĂĄ-lo uma vez em **um processo** pode atender a vĂĄrios clientes simultaneamente.
+Com uma aplicação FastAPI, usando um programa de servidor como o comando `fastapi` que executa o Uvicorn, executå-lo uma vez em **um processo** pode atender a vårios clientes simultaneamente.
Mas em muitos casos, vocĂȘ desejarĂĄ executar vĂĄrios processos de trabalho ao mesmo tempo.
### Processos MĂșltiplos - Trabalhadores { #multiple-processes-workers }
-Se vocĂȘ tiver mais clientes do que um Ășnico processo pode manipular (por exemplo, se a mĂĄquina virtual nĂŁo for muito grande) e tiver **vĂĄrios nĂșcleos** na CPU do servidor, vocĂȘ poderĂĄ ter **vĂĄrios processos** em execução com o mesmo aplicativo ao mesmo tempo e distribuir todas as solicitaçÔes entre eles.
+Se vocĂȘ tiver mais clientes do que um Ășnico processo pode manipular (por exemplo, se a mĂĄquina virtual nĂŁo for muito grande) e tiver **vĂĄrios nĂșcleos** na CPU do servidor, vocĂȘ poderĂĄ ter **vĂĄrios processos** em execução com a mesma aplicação ao mesmo tempo e distribuir todas as requests entre eles.
Quando vocĂȘ executa **vĂĄrios processos** do mesmo programa de API, eles sĂŁo comumente chamados de **trabalhadores**.
Este Processo de Gerenciador provavelmente seria o que escutaria na **porta** no IP. E ele transmitiria toda a comunicação para os processos de trabalho.
-Esses processos de trabalho seriam aqueles que executariam seu aplicativo, eles executariam os cĂĄlculos principais para receber uma **solicitação** e retornar uma **resposta**, e carregariam qualquer coisa que vocĂȘ colocasse em variĂĄveis ââna RAM.
+Esses processos de trabalho seriam aqueles que executariam sua aplicação, eles executariam os cĂĄlculos principais para receber uma **request** e retornar uma **resposta**, e carregariam qualquer coisa que vocĂȘ colocasse em variĂĄveis ââna RAM.
<img src="/img/deployment/concepts/process-ram.drawio.svg">
-E, claro, a mesma måquina provavelmente teria **outros processos** em execução, além do seu aplicativo.
+E, claro, a mesma måquina provavelmente teria **outros processos** em execução, além da sua aplicação.
Um detalhe interessante Ă© que a porcentagem da **CPU usada** por cada processo pode **variar** muito ao longo do tempo, mas a **memĂłria (RAM)** normalmente fica mais ou menos **estĂĄvel**.
Mas na maioria dos casos, vocĂȘ precisarĂĄ executar essas etapas apenas **uma vez**.
-Portanto, vocĂȘ vai querer ter um **processo Ășnico** para executar essas **etapas anteriores** antes de iniciar o aplicativo.
+Portanto, vocĂȘ vai querer ter um **processo Ășnico** para executar essas **etapas anteriores** antes de iniciar a aplicação.
-E vocĂȘ terĂĄ que se certificar de que Ă© um Ășnico processo executando essas etapas anteriores *mesmo* se depois, vocĂȘ iniciar **vĂĄrios processos** (vĂĄrios trabalhadores) para o prĂłprio aplicativo. Se essas etapas fossem executadas por **vĂĄrios processos**, eles **duplicariam** o trabalho executando-o em **paralelo**, e se as etapas fossem algo delicado como uma migração de banco de dados, elas poderiam causar conflitos entre si.
+E vocĂȘ terĂĄ que se certificar de que Ă© um Ășnico processo executando essas etapas anteriores *mesmo* se depois, vocĂȘ iniciar **vĂĄrios processos** (vĂĄrios trabalhadores) para a prĂłpria aplicação. Se essas etapas fossem executadas por **vĂĄrios processos**, eles **duplicariam** o trabalho executando-o em **paralelo**, e se as etapas fossem algo delicado como uma migração de banco de dados, elas poderiam causar conflitos entre si.
Claro, hĂĄ alguns casos em que nĂŁo hĂĄ problema em executar as etapas anteriores vĂĄrias vezes; nesse caso, Ă© muito mais fĂĄcil de lidar.
Aqui estĂŁo algumas ideias possĂveis:
* Um "Init Container" no Kubernetes que roda antes do seu app container
-* Um script bash que roda os passos anteriores e entĂŁo inicia seu aplicativo
+* Um script bash que roda os passos anteriores e então inicia sua aplicação
* VocĂȘ ainda precisaria de uma maneira de iniciar/reiniciar *aquele* script bash, detectar erros, etc.
/// tip | Dica
## Recapitular { #recap }
-VocĂȘ leu aqui alguns dos principais conceitos que provavelmente precisa ter em mente ao decidir como implantar seu aplicativo:
+VocĂȘ leu aqui alguns dos principais conceitos que provavelmente precisa ter em mente ao decidir como implantar sua aplicação:
* Segurança - HTTPS
* Executando na inicialização
Em contraste com a "**imagem de contĂȘiner**" que contĂ©m os conteĂșdos estĂĄticos armazenados, um "**contĂȘiner**" normalmente se refere Ă instĂąncia rodando, a coisa que estĂĄ sendo **executada**.
-Quando o **contĂȘiner** Ă© iniciado e estĂĄ rodando (iniciado a partir de uma **imagem de contĂȘiner**), ele pode criar ou modificar arquivos, variĂĄveis de ambiente, etc. Essas mudanças vĂŁo existir somente nesse contĂȘiner, mas nĂŁo persistirĂŁo na imagem subjacente do container (nĂŁo serĂŁo salvas no disco).
+Quando o **contĂȘiner** Ă© iniciado e estĂĄ rodando (iniciado a partir de uma **imagem de contĂȘiner**), ele pode criar ou modificar arquivos, variĂĄveis de ambiente, etc. Essas mudanças vĂŁo existir somente nesse contĂȘiner, mas nĂŁo persistirĂŁo na imagem subjacente do contĂȘiner (nĂŁo serĂŁo salvas no disco).
Uma imagem de contĂȘiner Ă© comparĂĄvel ao arquivo de **programa** e seus conteĂșdos, ex.: `python` e algum arquivo `main.py`.
Por exemplo, hĂĄ uma [Imagem Python](https://hub.docker.com/_/python) oficial.
-E existe muitas outras imagens para diferentes coisas, como bancos de dados, por exemplo:
+E existem muitas outras imagens para diferentes coisas, como bancos de dados, por exemplo:
* [PostgreSQL](https://hub.docker.com/_/postgres)
* [MySQL](https://hub.docker.com/_/mysql)
Um contĂȘiner estĂĄ rodando enquanto o **processo principal** (comando ou programa) estiver rodando.
-Um contĂȘiner normalmente tem um **Ășnico processo**, mas tambĂ©m Ă© possĂvel iniciar sub-processos a partir do processo principal, e dessa forma vocĂȘ terĂĄ **vĂĄrios processos** no mesmo contĂȘiner.
+Um contĂȘiner normalmente tem um **Ășnico processo**, mas tambĂ©m Ă© possĂvel iniciar subprocessos a partir do processo principal, e dessa forma vocĂȘ terĂĄ **vĂĄrios processos** no mesmo contĂȘiner.
Mas nĂŁo Ă© possĂvel ter um contĂȘiner rodando sem **pelo menos um processo rodando**. Se o processo principal parar, o contĂȘiner tambĂ©m para.
-## Construir uma Imagem Docker para FastAPI { #build-a-docker-image-for-fastapi }
+## Construa uma Imagem Docker para FastAPI { #build-a-docker-image-for-fastapi }
Okay, vamos construir algo agora! đ
#### Estrutura de diretĂłrios { #directory-structure }
-Agora vocĂȘ deve haver uma estrutura de diretĂłrio como:
+Agora vocĂȘ deveria ter uma estrutura de diretĂłrio como:
```
.
#### Por trås de um Proxy de Terminação TLS { #behind-a-tls-termination-proxy }
-Se vocĂȘ estĂĄ executando seu contĂȘiner atrĂĄs de um Proxy de Terminação TLS (load balancer) como Nginx ou Traefik, adicione a opção `--proxy-headers`, isso farĂĄ com que o Uvicorn (pela CLI do FastAPI) confie nos cabeçalhos enviados por esse proxy, informando que o aplicativo estĂĄ sendo executado atrĂĄs do HTTPS, etc.
+Se vocĂȘ estĂĄ executando seu contĂȘiner atrĂĄs de um Proxy de Terminação TLS (balanceador de carga) como Nginx ou Traefik, adicione a opção `--proxy-headers`, isso farĂĄ com que o Uvicorn (pela CLI do FastAPI) confie nos cabeçalhos enviados por esse proxy, informando que o aplicativo estĂĄ sendo executado atrĂĄs do HTTPS, etc.
```Dockerfile
CMD ["fastapi", "run", "app/main.py", "--proxy-headers", "--port", "80"]
COPY ./requirements.txt /code/requirements.txt
```
-Docker e outras ferramentas **constrĂłem** essas imagens de contĂȘiner **incrementalmente**, adicionando **uma camada em cima da outra**, começando do topo do `Dockerfile` e adicionando qualquer arquivo criado por cada uma das instruçÔes do `Dockerfile`.
+Docker e outras ferramentas **constroem** essas imagens de contĂȘiner **incrementalmente**, adicionando **uma camada em cima da outra**, começando do topo do `Dockerfile` e adicionando qualquer arquivo criado por cada uma das instruçÔes do `Dockerfile`.
Docker e ferramentas similares tambĂ©m usam um **cache interno** ao construir a imagem, se um arquivo nĂŁo mudou desde a Ășltima vez que a imagem do contĂȘiner foi construĂda, entĂŁo ele irĂĄ **reutilizar a mesma camada** criada na Ășltima vez, ao invĂ©s de copiar o arquivo novamente e criar uma nova camada do zero.
## Verifique { #check-it }
-VocĂȘ deve ser capaz de verificar isso no URL do seu contĂȘiner Docker, por exemplo: [http://192.168.99.100/items/5?q=somequery](http://192.168.99.100/items/5?q=somequery) ou [http://127.0.0.1/items/5?q=somequery](http://127.0.0.1/items/5?q=somequery) (ou equivalente, usando seu host Docker).
+VocĂȘ deveria conseguir verificar isso no URL do seu contĂȘiner Docker, por exemplo: [http://192.168.99.100/items/5?q=somequery](http://192.168.99.100/items/5?q=somequery) ou [http://127.0.0.1/items/5?q=somequery](http://127.0.0.1/items/5?q=somequery) (ou equivalente, usando seu host Docker).
VocĂȘ verĂĄ algo como:
-## Construa uma Imagem Docker com um FastAPI de Arquivo Ănico { #build-a-docker-image-with-a-single-file-fastapi }
+## Construa uma Imagem Docker com uma aplicação FastAPI de Arquivo Ănico { #build-a-docker-image-with-a-single-file-fastapi }
-Se seu FastAPI for um Ășnico arquivo, por exemplo, `main.py` sem um diretĂłrio `./app`, sua estrutura de arquivos poderia ser assim:
+Se sua aplicação FastAPI for um Ășnico arquivo, por exemplo, `main.py` sem um diretĂłrio `./app`, sua estrutura de arquivos poderia ser assim:
```
.
Se vocĂȘ tiver um <dfn title="Um grupo de mĂĄquinas que sĂŁo configuradas para estarem conectadas e trabalharem juntas de alguma forma.">cluster</dfn> de mĂĄquinas com **Kubernetes**, Docker Swarm Mode, Nomad ou outro sistema complexo semelhante para gerenciar contĂȘineres distribuĂdos em vĂĄrias mĂĄquinas, entĂŁo provavelmente desejarĂĄ **lidar com a replicação** no **nĂvel do cluster** em vez de usar um **gerenciador de processos** (como Uvicorn com workers) em cada contĂȘiner.
-Um desses sistemas de gerenciamento de contĂȘineres distribuĂdos como o Kubernetes normalmente tem alguma maneira integrada de lidar com a **replicação de contĂȘineres** enquanto ainda oferece **balanceamento de carga** para as solicitaçÔes recebidas. Tudo no **nĂvel do cluster**.
+Um desses sistemas de gerenciamento de contĂȘineres distribuĂdos como o Kubernetes normalmente tem alguma maneira integrada de lidar com a **replicação de contĂȘineres** enquanto ainda oferece **balanceamento de carga** para os requests recebidos. Tudo no **nĂvel do cluster**.
Nesses casos, vocĂȘ provavelmente desejarĂĄ criar uma **imagem Docker do zero** como [explicado acima](#dockerfile), instalando suas dependĂȘncias e executando **um Ășnico processo Uvicorn** em vez de usar mĂșltiplos workers do Uvicorn.
Quando usando contĂȘineres, normalmente vocĂȘ terĂĄ algum componente **escutando na porta principal**. Poderia ser outro contĂȘiner que tambĂ©m Ă© um **Proxy de Terminação TLS** para lidar com **HTTPS** ou alguma ferramenta semelhante.
-Como esse componente assumiria a **carga** de solicitaçÔes e distribuiria isso entre os workers de uma maneira (esperançosamente) **balanceada**, ele também é comumente chamado de **Balanceador de Carga**.
+Como esse componente assumiria a **carga** de requests e distribuiria isso entre os workers de uma maneira (esperançosamente) **balanceada**, ele também é comumente chamado de **Balanceador de Carga**.
/// tip | Dica
///
-E quando trabalhar com contĂȘineres, o mesmo sistema que vocĂȘ usa para iniciar e gerenciĂĄ-los jĂĄ terĂĄ ferramentas internas para transmitir a **comunicação de rede** (por exemplo, solicitaçÔes HTTP) do **balanceador de carga** (que tambĂ©m pode ser um **Proxy de Terminação TLS**) para o(s) contĂȘiner(es) com seu aplicativo.
+E quando trabalhar com contĂȘineres, o mesmo sistema que vocĂȘ usa para iniciar e gerenciĂĄ-los jĂĄ terĂĄ ferramentas internas para transmitir a **comunicação de rede** (por exemplo, requests HTTP) do **balanceador de carga** (que tambĂ©m pode ser um **Proxy de Terminação TLS**) para o(s) contĂȘiner(es) com seu aplicativo.
### Um Balanceador de Carga - MĂșltiplos ContĂȘineres de Workers { #one-load-balancer-multiple-worker-containers }
-Quando trabalhando com **Kubernetes** ou sistemas similares de gerenciamento de contĂȘiner distribuĂdo, usar seus mecanismos de rede internos permite que o Ășnico **balanceador de carga** que estĂĄ escutando na **porta principal** transmita a comunicação (solicitaçÔes) para possivelmente **mĂșltiplos contĂȘineres** executando seu aplicativo.
+Quando trabalhando com **Kubernetes** ou sistemas similares de gerenciamento de contĂȘiner distribuĂdo, usar seus mecanismos de rede internos permite que o Ășnico **balanceador de carga** que estĂĄ escutando na **porta principal** transmita a comunicação (requests) para possivelmente **mĂșltiplos contĂȘineres** executando seu aplicativo.
Cada um desses contĂȘineres executando seu aplicativo normalmente teria **apenas um processo** (ex.: um processo Uvicorn executando seu aplicativo FastAPI). Todos seriam **contĂȘineres idĂȘnticos**, executando a mesma coisa, mas cada um com seu prĂłprio processo, memĂłria, etc. Dessa forma, vocĂȘ aproveitaria a **paralelização** em **nĂșcleos diferentes** da CPU, ou atĂ© mesmo em **mĂĄquinas diferentes**.
-E o sistema de contĂȘiner com o **balanceador de carga** iria **distribuir as solicitaçÔes** para cada um dos contĂȘineres com seu aplicativo **em turnos**. Portanto, cada solicitação poderia ser tratada por um dos mĂșltiplos **contĂȘineres replicados** executando seu aplicativo.
+E o sistema de contĂȘiner com o **balanceador de carga** iria **distribuir os requests** para cada um dos contĂȘineres com seu aplicativo **em turnos**. Portanto, cada request poderia ser tratado por um dos mĂșltiplos **contĂȘineres replicados** executando seu aplicativo.
-E normalmente esse **balanceador de carga** seria capaz de lidar com solicitaçÔes que vĂŁo para *outros* aplicativos em seu cluster (por exemplo, para um domĂnio diferente, ou sob um prefixo de URL diferente), e transmitiria essa comunicação para os contĂȘineres certos para *esse outro* aplicativo em execução em seu cluster.
+E normalmente esse **balanceador de carga** seria capaz de lidar com requests que vĂŁo para *outros* aplicativos em seu cluster (por exemplo, para um domĂnio diferente, ou sob um prefixo de path de URL diferente), e transmitiria essa comunicação para os contĂȘineres certos para *esse outro* aplicativo em execução em seu cluster.
### Um Processo por ContĂȘiner { #one-process-per-container }
E entĂŁo vocĂȘ pode definir esses mesmos limites e requisitos de memĂłria em suas configuraçÔes para seu sistema de gerenciamento de contĂȘineres (por exemplo, no **Kubernetes**). Dessa forma, ele poderĂĄ **replicar os contĂȘineres** nas **mĂĄquinas disponĂveis** levando em consideração a quantidade de memĂłria necessĂĄria por eles e a quantidade disponĂvel nas mĂĄquinas no cluster.
-Se sua aplicação for **simples**, isso provavelmente **nĂŁo serĂĄ um problema**, e vocĂȘ pode nĂŁo precisar especificar limites de memĂłria rĂgidos. Mas se vocĂȘ estiver **usando muita memĂłria** (por exemplo, com **modelos de aprendizado de mĂĄquina**), deve verificar quanta memĂłria estĂĄ consumindo e ajustar o **nĂșmero de contĂȘineres** que executa em **cada mĂĄquina** (e talvez adicionar mais mĂĄquinas ao seu cluster).
+Se sua aplicação for **simples**, isso provavelmente **nĂŁo serĂĄ um problema**, e vocĂȘ pode nĂŁo precisar especificar limites de memĂłria rĂgidos. Mas se vocĂȘ estiver **usando muita memĂłria** (por exemplo, com modelos de **Aprendizado de MĂĄquina**), vocĂȘ deveria verificar quanta memĂłria estĂĄ consumindo e ajustar o **nĂșmero de contĂȘineres** que executa em **cada mĂĄquina** (e talvez adicionar mais mĂĄquinas ao seu cluster).
Se vocĂȘ executar **mĂșltiplos processos por contĂȘiner**, deve garantir que o nĂșmero de processos iniciados nĂŁo **consuma mais memĂłria** do que o disponĂvel.
Antes havia uma imagem oficial do FastAPI para Docker: [tiangolo/uvicorn-gunicorn-fastapi](https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker). Mas agora ela estĂĄ descontinuada. âïž
-VocĂȘ provavelmente **nĂŁo** deve usar essa imagem base do Docker (ou qualquer outra semelhante).
+VocĂȘ provavelmente **nĂŁo** deveria usar essa imagem base do Docker (ou qualquer outra semelhante).
Se vocĂȘ estĂĄ usando **Kubernetes** (ou outros) e jĂĄ estĂĄ definindo a **replicação** no nĂvel do cluster, com vĂĄrios **contĂȘineres**. Nesses casos, Ă© melhor **construir uma imagem do zero** como descrito acima: [Construir uma Imagem Docker para FastAPI](#build-a-docker-image-for-fastapi).
///
-Para aprender o bĂĄsico de HTTPS do ponto de vista do consumidor, verifique [https://howhttps.works/](https://howhttps.works/).
-
-Agora, a partir de uma perspectiva do desenvolvedor, aqui estĂŁo algumas coisas para ter em mente ao pensar em HTTPS:
-
-* Para HTTPS, o servidor precisa ter "certificados" gerados por um terceiro.
- * Esses certificados sĂŁo na verdade adquiridos de um terceiro, eles nĂŁo sĂŁo simplesmente "gerados".
-* Certificados tĂȘm um tempo de vida.
- * Eles expiram.
- * E entĂŁo eles precisam ser renovados, adquirindo-os novamente de um terceiro.
-* A criptografia da conexĂŁo acontece no nĂvel TCP.
- * Essa Ă© uma camada abaixo do HTTP.
- * Portanto, o manuseio do certificado e da criptografia Ă© feito antes do HTTP.
-* O TCP nĂŁo sabe sobre "domĂnios". Apenas sobre endereços IP.
- * As informaçÔes sobre o domĂnio especĂfico solicitado vĂŁo nos dados HTTP.
-* Os certificados HTTPS âcertificamâ um determinado domĂnio, mas o protocolo e a encriptação acontecem ao nĂvel do TCP, antes de sabermos de que domĂnio se trata.
-* Por padrĂŁo, isso significa que vocĂȘ sĂł pode ter um certificado HTTPS por endereço IP.
+Para **aprender o bĂĄsico de HTTPS**, do ponto de vista do consumidor, verifique [https://howhttps.works/](https://howhttps.works/).
+
+Agora, a partir de uma **perspectiva do desenvolvedor**, aqui estĂŁo algumas coisas para ter em mente ao pensar em HTTPS:
+
+* Para HTTPS, **o servidor** precisa **ter "certificados"** gerados por um **terceiro**.
+ * Esses certificados sĂŁo na verdade **adquiridos** de um terceiro, eles nĂŁo sĂŁo simplesmente "gerados".
+* Certificados tĂȘm um **tempo de vida**.
+ * Eles **expiram**.
+ * E entĂŁo eles precisam ser **renovados**, **adquiridos novamente** de um terceiro.
+* A criptografia da conexĂŁo acontece no **nĂvel TCP**.
+ * Essa Ă© uma camada **abaixo do HTTP**.
+ * Portanto, o manuseio do **certificado e da criptografia** Ă© feito **antes do HTTP**.
+* **O TCP nĂŁo sabe sobre "domĂnios"**. Apenas sobre endereços IP.
+ * As informaçÔes sobre o **domĂnio especĂfico** solicitado vĂŁo nos **dados HTTP**.
+* Os **certificados HTTPS** âcertificamâ um **determinado domĂnio**, mas o protocolo e a encriptação acontecem ao nĂvel do TCP, **antes de sabermos** de que domĂnio se trata.
+* **Por padrĂŁo**, isso significa que vocĂȘ sĂł pode ter **um certificado HTTPS por endereço IP**.
* NĂŁo importa o tamanho do seu servidor ou quĂŁo pequeno cada aplicativo que vocĂȘ tem nele possa ser.
- * No entanto, existe uma solução para isso.
-* HĂĄ uma extensĂŁo para o protocolo TLS (aquele que lida com a criptografia no nĂvel TCP, antes do HTTP) chamada [<abbr title="Server Name Indication - Indicação do Nome do Servidor">SNI</abbr>](https://en.wikipedia.org/wiki/Server_Name_Indication).
- * Esta extensĂŁo SNI permite que um Ășnico servidor (com um Ășnico endereço IP) tenha vĂĄrios certificados HTTPS e atenda a vĂĄrios domĂnios / aplicativos HTTPS.
- * Para que isso funcione, um Ășnico componente (programa) em execução no servidor, ouvindo no endereço IP pĂșblico, deve ter todos os certificados HTTPS no servidor.
-* Depois de obter uma conexão segura, o protocolo de comunicação ainda é HTTP.
- * Os conteĂșdos sĂŁo criptografados, embora sejam enviados com o protocolo HTTP.
+ * No entanto, existe uma **solução** para isso.
+* HĂĄ uma **extensĂŁo** para o protocolo **TLS** (aquele que lida com a criptografia no nĂvel TCP, antes do HTTP) chamada **[<abbr title="Server Name Indication - Indicação do Nome do Servidor">SNI</abbr>](https://en.wikipedia.org/wiki/Server_Name_Indication)**.
+ * Esta extensĂŁo SNI permite que um Ășnico servidor (com um **Ășnico endereço IP**) tenha **vĂĄrios certificados HTTPS** e atenda a **vĂĄrios domĂnios / aplicativos HTTPS**.
+ * Para que isso funcione, um **Ășnico** componente (programa) em execução no servidor, ouvindo no **endereço IP pĂșblico**, deve ter **todos os certificados HTTPS** no servidor.
+* **Depois** de obter uma conexão segura, o protocolo de comunicação ainda é **HTTP**.
+ * Os conteĂșdos sĂŁo **criptografados**, embora sejam enviados com o **protocolo HTTP**.
-à uma pråtica comum ter um programa/servidor HTTP em execução no servidor (måquina, host, etc.) e gerenciar todas as partes HTTPS: recebendo as requisiçÔes HTTPS encriptadas, enviando as solicitaçÔes HTTP descriptografadas para o aplicativo HTTP real em execução no mesmo servidor (a aplicação FastAPI, neste caso), pegar a resposta HTTP do aplicativo, criptografå-la usando o certificado HTTPS apropriado e enviå-la de volta ao cliente usando HTTPS. Este servidor é frequentemente chamado de [Proxy de Terminação TLS](https://en.wikipedia.org/wiki/TLS_termination_proxy).
+à uma pråtica comum ter **um programa/servidor HTTP** em execução no servidor (måquina, host, etc.) e **gerenciar todas as partes HTTPS**: recebendo as **requisiçÔes HTTPS encriptadas**, enviando as **solicitaçÔes HTTP descriptografadas** para o aplicativo HTTP real em execução no mesmo servidor (a aplicação **FastAPI**, neste caso), pegar a **resposta HTTP** do aplicativo, **criptografå-la** usando o **certificado HTTPS** apropriado e enviå-la de volta ao cliente usando **HTTPS**. Este servidor é frequentemente chamado de **[Proxy de Terminação TLS](https://en.wikipedia.org/wiki/TLS_termination_proxy)**.
Algumas das opçÔes que vocĂȘ pode usar como Proxy de Terminação TLS sĂŁo:
## Let's Encrypt { #lets-encrypt }
-Antes de Let's Encrypt, esses certificados HTTPS eram vendidos por terceiros confiĂĄveis.
+Antes de Let's Encrypt, esses **certificados HTTPS** eram vendidos por terceiros confiĂĄveis.
O processo de aquisição de um desses certificados costumava ser complicado, exigia bastante papelada e os certificados eram bastante caros.
-Mas entĂŁo o [Let's Encrypt](https://letsencrypt.org/) foi criado.
+Mas entĂŁo o **[Let's Encrypt](https://letsencrypt.org/)** foi criado.
-Ele Ă© um projeto da Linux Foundation que fornece certificados HTTPS gratuitamente. De forma automatizada. Esses certificados usam toda a segurança criptogrĂĄfica padrĂŁo e tĂȘm vida curta (cerca de 3 meses), entĂŁo a segurança Ă©, na verdade, melhor por causa do seu lifespan reduzido.
+Ele Ă© um projeto da Linux Foundation. Ele fornece **certificados HTTPS gratuitamente**, de forma automatizada. Esses certificados usam toda a segurança criptogrĂĄfica padrĂŁo e tĂȘm vida curta (cerca de 3 meses), entĂŁo a **segurança Ă©, na verdade, melhor** por causa do seu lifespan reduzido.
Os domĂnios sĂŁo verificados com segurança e os certificados sĂŁo gerados automaticamente. Isso tambĂ©m permite automatizar a renovação desses certificados.
-A ideia Ă© automatizar a aquisição e renovação desses certificados, para que vocĂȘ tenha HTTPS seguro, de graça e para sempre.
+A ideia Ă© automatizar a aquisição e renovação desses certificados, para que vocĂȘ tenha **HTTPS seguro, de graça e para sempre**.
## HTTPS para Desenvolvedores { #https-for-developers }
### Nome do domĂnio { #domain-name }
-A etapa inicial provavelmente seria adquirir algum nome de domĂnio. EntĂŁo, vocĂȘ iria configurĂĄ-lo em um servidor DNS (possivelmente no mesmo provedor em nuvem).
+A etapa inicial provavelmente seria **adquirir** algum **nome de domĂnio**. EntĂŁo, vocĂȘ iria configurĂĄ-lo em um servidor DNS (possivelmente no mesmo provedor em nuvem).
-VocĂȘ provavelmente usaria um servidor em nuvem (mĂĄquina virtual) ou algo parecido, e ele teria um <dfn title="NĂŁo muda ao longo do tempo. NĂŁo Ă© dinĂąmico.">fixo</dfn> Endereço IP pĂșblico.
+VocĂȘ provavelmente usaria um servidor em nuvem (mĂĄquina virtual) ou algo parecido, e ele teria um **endereço IP pĂșblico** <dfn title="NĂŁo muda ao longo do tempo. NĂŁo Ă© dinĂąmico.">fixo</dfn>.
-No(s) servidor(es) DNS, vocĂȘ configuraria um registro (um `A record`) para apontar seu domĂnio para o endereço IP pĂșblico do seu servidor.
+No(s) servidor(es) DNS, vocĂȘ configuraria um registro (um "`A record`") para apontar **seu domĂnio** para o **endereço IP pĂșblico do seu servidor**.
VocĂȘ provavelmente farĂĄ isso apenas uma vez, na primeira vez em que tudo estiver sendo configurado.
Agora vamos focar em todas as partes que realmente fazem parte do HTTPS.
-Primeiro, o navegador iria verificar com os servidores DNS qual o IP do domĂnio, nesse caso, `someapp.example.com`.
+Primeiro, o navegador iria verificar com os **servidores DNS** qual o **IP do domĂnio**, nesse caso, `someapp.example.com`.
-Os servidores DNS iriam informar o navegador para utilizar algum endereço IP especĂfico. Esse seria o endereço IP pĂșblico em uso no seu servidor, que vocĂȘ configurou nos servidores DNS.
+Os servidores DNS iriam informar o navegador para utilizar algum **endereço IP** especĂfico. Esse seria o endereço IP pĂșblico em uso no seu servidor, que vocĂȘ configurou nos servidores DNS.
<img src="/img/deployment/https/https01.drawio.svg">
### InĂcio do Handshake TLS { #tls-handshake-start }
-O navegador então irå comunicar-se com esse endereço IP na porta 443 (a porta HTTPS).
+O navegador então irå comunicar-se com esse endereço IP na **porta 443** (a porta HTTPS).
A primeira parte dessa comunicação é apenas para estabelecer a conexão entre o cliente e o servidor e para decidir as chaves criptogråficas a serem utilizadas, etc.
<img src="/img/deployment/https/https02.drawio.svg">
-Esse interação entre o cliente e o servidor para estabelecer uma conexão TLS é chamada de Handshake TLS.
+Esse interação entre o cliente e o servidor para estabelecer uma conexão TLS é chamada de **Handshake TLS**.
### TLS com a ExtensĂŁo SNI { #tls-with-sni-extension }
-Apenas um processo no servidor pode se conectar a uma porta em um endereço IP. Poderiam existir outros processos conectados em outras portas desse mesmo endereço IP, mas apenas um para cada combinação de endereço IP e porta.
+**Apenas um processo** no servidor pode se conectar a uma **porta** em um **endereço IP**. Poderiam existir outros processos conectados em outras portas desse mesmo endereço IP, mas apenas um para cada combinação de endereço IP e porta.
TLS (HTTPS) usa a porta `443` por padrĂŁo. EntĂŁo essa Ă© a porta que precisamos.
-Como apenas um Ășnico processo pode se comunicar com essa porta, o processo que faria isso seria o Proxy de Terminação TLS.
+Como apenas um Ășnico processo pode se comunicar com essa porta, o processo que faria isso seria o **Proxy de Terminação TLS**.
-O Proxy de Terminação TLS teria acesso a um ou mais certificados TLS (certificados HTTPS).
+O Proxy de Terminação TLS teria acesso a um ou mais **certificados TLS** (certificados HTTPS).
-Utilizando a extensĂŁo SNI discutida acima, o Proxy de Terminação TLS iria checar qual dos certificados TLS (HTTPS) disponĂveis deve ser usado para essa conexĂŁo, utilizando o que corresponda ao domĂnio esperado pelo cliente.
+Utilizando a **extensĂŁo SNI** discutida acima, o Proxy de Terminação TLS iria checar qual dos certificados TLS (HTTPS) disponĂveis deve ser usado para essa conexĂŁo, utilizando o que corresponda ao domĂnio esperado pelo cliente.
Nesse caso, ele usaria o certificado para `someapp.example.com`.
<img src="/img/deployment/https/https03.drawio.svg">
-O cliente jĂĄ confia na entidade que gerou o certificado TLS (nesse caso, o Let's Encrypt, mas veremos sobre isso mais tarde), entĂŁo ele pode verificar que o certificado Ă© vĂĄlido.
+O cliente jĂĄ **confia** na entidade que gerou o certificado TLS (nesse caso, o Let's Encrypt, mas veremos sobre isso mais tarde), entĂŁo ele pode **verificar** que o certificado Ă© vĂĄlido.
-Então, utilizando o certificado, o cliente e o Proxy de Terminação TLS decidem como encriptar o resto da comunicação TCP. Isso completa a parte do Handshake TLS.
+Então, utilizando o certificado, o cliente e o Proxy de Terminação TLS **decidem como encriptar** o resto da **comunicação TCP**. Isso completa a parte do **Handshake TLS**.
-Após isso, o cliente e o servidor possuem uma conexão TCP encriptada, que é provida pelo TLS. E então eles podem usar essa conexão para começar a comunicação HTTP propriamente dita.
+Após isso, o cliente e o servidor possuem uma **conexão TCP encriptada**, que é provida pelo TLS. E então eles podem usar essa conexão para começar a **comunicação HTTP** propriamente dita.
-E isso resume o que Ă© HTTPS, apenas HTTP simples dentro de uma conexĂŁo TLS segura em vez de uma conexĂŁo TCP pura (nĂŁo encriptada).
+E isso resume o que Ă© **HTTPS**, apenas **HTTP** simples dentro de uma **conexĂŁo TLS segura** em vez de uma conexĂŁo TCP pura (nĂŁo encriptada).
/// tip | Dica
-Percebe que a encriptação da comunicação acontece no nĂvel do TCP, nĂŁo no nĂvel do HTTP.
+Perceba que a encriptação da comunicação acontece no **nĂvel do TCP**, nĂŁo no nĂvel do HTTP.
///
### Solicitação HTTPS { #https-request }
-Agora que o cliente e servidor (especialmente o navegador e o Proxy de Terminação TLS) possuem uma conexão TCP encriptada, eles podem iniciar a comunicação HTTP.
+Agora que o cliente e servidor (especialmente o navegador e o Proxy de Terminação TLS) possuem uma **conexão TCP encriptada**, eles podem iniciar a **comunicação HTTP**.
-Então, o cliente envia uma solicitação HTTPS. Que é apenas uma solicitação HTTP sobre uma conexão TLS encriptada.
+Então, o cliente envia uma **solicitação HTTPS**. Que é apenas uma solicitação HTTP sobre uma conexão TLS encriptada.
<img src="/img/deployment/https/https04.drawio.svg">
### Desencripte a Solicitação { #decrypt-the-request }
-O Proxy de Terminação TLS então usaria a encriptação combinada para desencriptar a solicitação, e transmitiria a solicitação båsica (desencriptada) para o processo executando a aplicação (por exemplo, um processo com Uvicorn executando a aplicação FastAPI).
+O Proxy de Terminação TLS então usaria a encriptação combinada para **desencriptar a solicitação**, e transmitiria a **solicitação HTTP båsica (desencriptada)** para o processo executando a aplicação (por exemplo, um processo com Uvicorn executando a aplicação FastAPI).
<img src="/img/deployment/https/https05.drawio.svg">
### Resposta HTTP { #http-response }
-A aplicação processaria a solicitação e retornaria uma resposta HTTP båsica (não encriptada) para o Proxy de Terminação TLS.
+A aplicação processaria a solicitação e retornaria uma **resposta HTTP båsica (não encriptada)** para o Proxy de Terminação TLS.
<img src="/img/deployment/https/https06.drawio.svg">
### Resposta HTTPS { #https-response }
-O Proxy de Terminação TLS iria encriptar a resposta utilizando a criptografia combinada anteriormente (que foi definida com o certificado para `someapp.example.com`), e devolveria para o navegador.
+O Proxy de Terminação TLS iria **encriptar a resposta** utilizando a criptografia combinada anteriormente (que foi definida com o certificado para `someapp.example.com`), e devolveria para o navegador.
-No prĂłximo passo, o navegador verifica que a resposta Ă© vĂĄlida e encriptada com a chave criptogrĂĄfica correta, etc. E depois desencripta a resposta e a processa.
+No prĂłximo passo, o navegador verifica que a resposta Ă© vĂĄlida e encriptada com a chave criptogrĂĄfica correta, etc. E depois **desencripta a resposta** e a processa.
<img src="/img/deployment/https/https07.drawio.svg">
-O cliente (navegador) saberĂĄ que a resposta vem do servidor correto por que ela usa a criptografia que foi combinada entre eles usando o certificado HTTPS anterior.
+O cliente (navegador) saberĂĄ que a resposta vem do servidor correto por que ela usa a criptografia que foi combinada entre eles usando o **certificado HTTPS** anterior.
### MĂșltiplas AplicaçÔes { #multiple-applications }
-Podem existir mĂșltiplas aplicaçÔes em execução no mesmo servidor (ou servidores), por exemplo: outras APIs ou um banco de dados.
+Podem existir **mĂșltiplas aplicaçÔes** em execução no mesmo servidor (ou servidores), por exemplo: outras APIs ou um banco de dados.
-Apenas um processo pode estar vinculado a um IP e porta (o Proxy de Terminação TLS, por exemplo), mas outras aplicaçÔes/processos tambĂ©m podem estar em execução no(s) servidor(es), desde que nĂŁo tentem usar a mesma combinação de IP pĂșblico e porta.
+Apenas um processo pode estar vinculado a um IP e porta (o Proxy de Terminação TLS, por exemplo), mas outras aplicaçÔes/processos tambĂ©m podem estar em execução no(s) servidor(es), desde que nĂŁo tentem usar a mesma **combinação de IP pĂșblico e porta**.
<img src="/img/deployment/https/https08.drawio.svg">
-Dessa forma, o Proxy de Terminação TLS pode gerenciar o HTTPS e os certificados de mĂșltiplos domĂnios, para mĂșltiplas aplicaçÔes, e entĂŁo transmitir as requisiçÔes para a aplicação correta em cada caso.
+Dessa forma, o Proxy de Terminação TLS pode gerenciar o HTTPS e os certificados de **mĂșltiplos domĂnios**, para mĂșltiplas aplicaçÔes, e entĂŁo transmitir as requisiçÔes para a aplicação correta em cada caso.
### Renovação de Certificados { #certificate-renewal }
-Em algum momento futuro, cada certificado irå expirar (aproximadamente 3 meses após a aquisição).
+Em algum momento futuro, cada certificado irå **expirar** (aproximadamente 3 meses após a aquisição).
-E então, haverå outro programa (em alguns casos pode ser o próprio Proxy de Terminação TLS) que irå interagir com o Let's Encrypt e renovar o(s) certificado(s).
+E então, haverå outro programa (em alguns casos é outro programa, em alguns casos pode ser o próprio Proxy de Terminação TLS) que irå interagir com o Let's Encrypt e renovar o(s) certificado(s).
<img src="/img/deployment/https/https.drawio.svg">
-Os certificados TLS sĂŁo associados com um nome de domĂnio, e nĂŁo a um endereço IP.
+Os **certificados TLS** sĂŁo **associados com um nome de domĂnio**, e nĂŁo a um endereço IP.
-EntĂŁo para renovar os certificados, o programa de renovação precisa provar para a autoridade (Let's Encrypt) que ele realmente "possui" e controla esse domĂnio.
+EntĂŁo para renovar os certificados, o programa de renovação precisa **provar** para a autoridade (Let's Encrypt) que ele realmente **"possui" e controla esse domĂnio**.
Para fazer isso, e acomodar as necessidades de diferentes aplicaçÔes, existem diferentes opçÔes para esse programa. Algumas escolhas populares são:
-* Modificar alguns registros DNS
+* **Modificar alguns registros DNS**.
* Para isso, o programa de renovação precisa ter suporte Ă s APIs do provedor DNS, entĂŁo, dependendo do provedor DNS que vocĂȘ utilize, isso pode ou nĂŁo ser uma opção viĂĄvel.
-* Executar como um servidor (ao menos durante o processo de aquisição do certificado) no endereço IP pĂșblico associado com o domĂnio.
+* **Executar como um servidor** (ao menos durante o processo de aquisição do certificado) no endereço IP pĂșblico associado com o domĂnio.
* Como dito anteriormente, apenas um processo pode estar ligado a uma porta e IP especĂficos.
* Essa Ă© uma dos motivos que fazem utilizar o mesmo Proxy de Terminação TLS para gerenciar a renovação de certificados ser tĂŁo Ăștil.
* Caso contrĂĄrio, vocĂȘ pode ter que parar a execução do Proxy de Terminação TLS momentaneamente, inicializar o programa de renovação para adquirir os certificados, depois configurĂĄ-los com o Proxy de Terminação TLS, e entĂŁo reiniciar o Proxy de Terminação TLS. Isso nĂŁo Ă© o ideal, jĂĄ que sua(s) aplicação(Ă”es) nĂŁo vĂŁo estar disponĂveis enquanto o Proxy de Terminação TLS estiver desligado.
-Todo esse processo de renovação, enquanto o aplicativo ainda funciona, é uma das principais razÔes para preferir um sistema separado para gerenciar HTTPS com um Proxy de Terminação TLS em vez de usar os certificados TLS no servidor da aplicação diretamente (e.g. com o Uvicorn).
+Todo esse processo de renovação, enquanto o aplicativo ainda funciona, é uma das principais razÔes para preferir um **sistema separado para gerenciar HTTPS** com um Proxy de Terminação TLS em vez de usar os certificados TLS no servidor da aplicação diretamente (e.g. com o Uvicorn).
## Cabeçalhos encaminhados por Proxy { #proxy-forwarded-headers }
-Ao usar um proxy para lidar com HTTPS, seu servidor de aplicação (por exemplo, Uvicorn via FastAPI CLI) não sabe nada sobre o processo de HTTPS; ele se comunica com HTTP simples com o Proxy de Terminação TLS.
+Ao usar um proxy para lidar com HTTPS, seu **servidor de aplicação** (por exemplo, Uvicorn via FastAPI CLI) não sabe nada sobre o processo de HTTPS; ele se comunica com HTTP simples com o **Proxy de Terminação TLS**.
-Esse proxy normalmente define alguns cabeçalhos HTTP dinamicamente antes de transmitir a requisição para o servidor de aplicação, para informar ao servidor de aplicação que a requisição estå sendo encaminhada pelo proxy.
+Esse **proxy** normalmente define alguns cabeçalhos HTTP dinamicamente antes de transmitir a requisição para o **servidor de aplicação**, para informar ao servidor de aplicação que a requisição estå sendo **encaminhada** pelo proxy.
/// note | Detalhes TĂ©cnicos
///
-No entanto, como o servidor de aplicação não sabe que estå atrås de um proxy confiåvel, por padrão ele não confiaria nesses cabeçalhos.
+No entanto, como o **servidor de aplicação** não sabe que estå atrås de um **proxy** confiåvel, por padrão ele não confiaria nesses cabeçalhos.
-Mas vocĂȘ pode configurar o servidor de aplicação para confiar nos cabeçalhos encaminhados enviados pelo proxy. Se vocĂȘ estiver usando o FastAPI CLI, pode usar a opção de CLI `--forwarded-allow-ips` para dizer de quais IPs ele deve confiar nesses cabeçalhos encaminhados.
+Mas vocĂȘ pode configurar o **servidor de aplicação** para confiar nos cabeçalhos *encaminhados* enviados pelo **proxy**. Se vocĂȘ estiver usando o FastAPI CLI, pode usar a *Opção de CLI* `--forwarded-allow-ips` para dizer de quais IPs ele deve confiar nesses cabeçalhos *encaminhados*.
-Por exemplo, se o servidor de aplicação sĂł estiver recebendo comunicação do proxy confiĂĄvel, vocĂȘ pode defini-lo como `--forwarded-allow-ips="*"` para fazĂȘ-lo confiar em todos os IPs de entrada, jĂĄ que ele sĂł receberĂĄ requisiçÔes de seja lĂĄ qual for o IP usado pelo proxy.
+Por exemplo, se o **servidor de aplicação** sĂł estiver recebendo comunicação do **proxy** confiĂĄvel, vocĂȘ pode defini-lo como `--forwarded-allow-ips="*"` para fazĂȘ-lo confiar em todos os IPs de entrada, jĂĄ que ele sĂł receberĂĄ requisiçÔes de seja lĂĄ qual for o IP usado pelo **proxy**.
Dessa forma, a aplicação seria capaz de saber qual Ă© sua prĂłpria URL pĂșblica, se estĂĄ usando HTTPS, o domĂnio, etc.
## Recapitulando { #recap }
-Possuir HTTPS habilitado na sua aplicação Ă© bastante importante, e atĂ© crĂtico na maioria dos casos. A maior parte do esforço que vocĂȘ tem que colocar sobre o HTTPS como desenvolvedor estĂĄ em entender esses conceitos e como eles funcionam.
+Possuir **HTTPS** habilitado na sua aplicação Ă© bastante importante, e atĂ© **crĂtico** na maioria dos casos. A maior parte do esforço que vocĂȘ tem que colocar sobre o HTTPS como desenvolvedor estĂĄ em **entender esses conceitos** e como eles funcionam.
-Mas uma vez que vocĂȘ saiba o bĂĄsico de HTTPS para desenvolvedores, vocĂȘ pode combinar e configurar diferentes ferramentas facilmente para gerenciar tudo de uma forma simples.
+Mas uma vez que vocĂȘ saiba o bĂĄsico de **HTTPS para desenvolvedores**, vocĂȘ pode combinar e configurar diferentes ferramentas facilmente para gerenciar tudo de uma forma simples.
-Em alguns dos prĂłximos capĂtulos, eu mostrarei para vocĂȘ vĂĄrios exemplos concretos de como configurar o HTTPS para aplicaçÔes FastAPI. đ
+Em alguns dos prĂłximos capĂtulos, eu mostrarei para vocĂȘ vĂĄrios exemplos concretos de como configurar o **HTTPS** para aplicaçÔes **FastAPI**. đ
Existem diversas alternativas, incluindo:
* [Uvicorn](https://www.uvicorn.dev/): um servidor ASGI de alta performance.
-* [Hypercorn](https://hypercorn.readthedocs.io/): um servidor ASGI compatĂvel com HTTP/2, Trio e outros recursos.
+* [Hypercorn](https://hypercorn.readthedocs.io/): um servidor ASGI compatĂvel com HTTP/2, Trio e outras funcionalidades.
* [Daphne](https://github.com/django/daphne): servidor ASGI construĂdo para Django Channels.
* [Granian](https://github.com/emmett-framework/granian): um servidor HTTP Rust para aplicaçÔes Python.
A opção `--reload` consome muito mais recursos, é mais inståvel, etc.
-Ela ajuda muito durante o **desenvolvimento**, mas vocĂȘ **nĂŁo deve** usĂĄ-la em **produção**.
+Ela ajuda muito durante o **desenvolvimento**, mas vocĂȘ **nĂŁo deveria** usĂĄ-la em **produção**.
///
# Suporte a Editores { #editor-support }
-A [FastAPI Extension](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) oficial melhora seu fluxo de trabalho de desenvolvimento com descoberta e navegação de *operação de rota*, além de implantação no FastAPI Cloud e transmissão ao vivo de logs.
+A [FastAPI Extension](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) oficial melhora seu fluxo de trabalho de desenvolvimento FastAPI com descoberta e navegação de *operação de rota*, além de implantação no FastAPI Cloud e transmissão ao vivo de logs.
Para mais detalhes sobre a extensĂŁo, consulte o README no [repositĂłrio do GitHub](https://github.com/fastapi/fastapi-vscode).
## ConclusĂŁo { #conclusion }
-Com isso, vocĂȘ deve ter uma compreensĂŁo bĂĄsica do que sĂŁo **variĂĄveis ââde ambiente** e como usĂĄ-las em Python.
+Com isso, vocĂȘ deveria ter uma compreensĂŁo bĂĄsica do que sĂŁo **variĂĄveis ââde ambiente** e como usĂĄ-las em Python.
VocĂȘ tambĂ©m pode ler mais sobre elas na [Wikipedia para VariĂĄveis ââde Ambiente](https://en.wikipedia.org/wiki/Environment_variable).
-# Recursos { #features }
+# Funcionalidades { #features }
-## Recursos do FastAPI { #fastapi-features }
+## Funcionalidades do FastAPI { #fastapi-features }
**FastAPI** te oferece o seguinte:
### Baseado em padrÔes abertos { #based-on-open-standards }
-* [**OpenAPI**](https://github.com/OAI/OpenAPI-Specification) para criação de APIs, incluindo declaraçÔes de <dfn title="também conhecido como: endpoints, rotas">caminho</dfn> <dfn title="também conhecido como métodos HTTP, como POST, GET, PUT, DELETE">operaçÔes</dfn>, parùmetros, requisiçÔes de corpo, segurança etc.
+* [**OpenAPI**](https://github.com/OAI/OpenAPI-Specification) para criação de APIs, incluindo declaraçÔes de <dfn title="também conhecido como: endpoints, rotas">path</dfn> <dfn title="também conhecido como métodos HTTP, como POST, GET, PUT, DELETE">operaçÔes</dfn>, parùmetros, corpos de requisição, segurança etc.
* Documentação automåtica de modelos de dados com [**JSON Schema**](https://json-schema.org/) (jå que o OpenAPI em si é baseado no JSON Schema).
* Projetado em torno desses padrÔes, após um estudo meticuloso. Em vez de uma camada improvisada por cima.
-* Isso também permite o uso de **geração de código do cliente** automaticamente em muitas linguagens.
+* Isso também permite o uso de **geração de código de cliente** automaticamente em muitas linguagens.
### Documentação automåtica { #automatic-docs }
Todo o framework foi projetado para ser fĂĄcil e intuitivo de usar, todas as decisĂ”es foram testadas em vĂĄrios editores antes do inĂcio do desenvolvimento, para garantir a melhor experiĂȘncia de desenvolvimento.
-Na pesquisa de desenvolvedores Python, ficou claro [que um dos recursos mais utilizados Ă© o "preenchimento automĂĄtico"](https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features).
+Nas pesquisas de desenvolvedores Python, ficou claro [que uma das funcionalidades mais utilizadas Ă© o "preenchimento automĂĄtico"](https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features).
Todo o framework **FastAPI** Ă© feito para satisfazer isso. O preenchimento automĂĄtico funciona em todos os lugares.
### Breve { #short }
-HĂĄ **padrĂ”es** sensĂveis para tudo, com configuraçÔes adicionais em todos os lugares. Todos os parĂąmetros podem ser regulados para fazer o que vocĂȘ precisa e para definir a API que vocĂȘ necessita.
+HĂĄ **valores padrĂŁo** sensĂveis para tudo, com configuraçÔes adicionais em todos os lugares. Todos os parĂąmetros podem ser regulados para fazer o que vocĂȘ precisa e para definir a API que vocĂȘ necessita.
-Por padrĂŁo, tudo **"simplesmente funciona"**.
+Mas, por padrĂŁo, tudo **"simplesmente funciona"**.
### Validação { #validation }
Segurança e autenticação integradas. Sem nenhum compromisso com bancos de dados ou modelos de dados.
-Todos os esquemas de seguranças definidos no OpenAPI, incluindo:
+Todos os esquemas de segurança definidos no OpenAPI, incluindo:
* HTTP Basic.
* **OAuth2** (também com **tokens JWT**). Confira o tutorial em [OAuth2 com JWT](tutorial/security/oauth2-jwt.md).
* parĂąmetros da Query.
* Cookies etc.
-Além disso, todos os recursos de segurança do Starlette (incluindo **cookies de sessão**).
+Além disso, todas as funcionalidades de segurança do Starlette (incluindo **cookies de sessão**).
-Tudo construĂdo como ferramentas e componentes reutilizĂĄveis que sĂŁo fĂĄceis de integrar com seus sistemas, armazenamento de dados, banco de dados relacionais e nĂŁo-relacionais etc.
+Tudo construĂdo como ferramentas e componentes reutilizĂĄveis que sĂŁo fĂĄceis de integrar com seus sistemas, armazenamentos de dados, bancos de dados relacionais e NoSQL etc.
### Injeção de dependĂȘncia { #dependency-injection }
* Tudo **automaticamente controlado** pelo framework.
* Todas as dependĂȘncias podem pedir dados das requisiçÔes e **ampliar** as restriçÔes e documentação automĂĄtica da **operação de rota**.
* **Validação automĂĄtica** mesmo para parĂąmetros da *operação de rota* definidos em dependĂȘncias.
-* Suporte para sistemas de autenticação complexos, **conexÔes com banco de dados** etc.
+* Suporte para sistemas complexos de autenticação de usuårios, **conexÔes com banco de dados** etc.
* **Sem comprometer** os bancos de dados, frontends etc. Mas fåcil integração com todos eles.
### "Plug-ins" ilimitados { #unlimited-plug-ins }
Ou, de outra forma, sem a necessidade deles, importe e use o cĂłdigo que precisar.
-Qualquer integração Ă© projetada para ser tĂŁo simples de usar (com dependĂȘncias) que vocĂȘ pode criar um "plug-in" para suas aplicaçÔes com 2 linhas de cĂłdigo usando a mesma estrutura e sintaxe para as suas *operaçÔes de rota*.
+Qualquer integração Ă© projetada para ser tĂŁo simples de usar (com dependĂȘncias) que vocĂȘ pode criar um "plug-in" para sua aplicação com 2 linhas de cĂłdigo usando a mesma estrutura e sintaxe usadas para as suas *operaçÔes de rota*.
### Testado { #tested }
* 100% <dfn title="A quantidade de cĂłdigo que Ă© testada automaticamente">de cobertura de testes</dfn>.
-* 100% do código com <dfn title="AnotaçÔes de tipo do Python, com isso seu editor e ferramentas externas podem te dar um suporte melhor">anotaçÔes de tipo</dfn>.
+* Base de código 100% <dfn title="AnotaçÔes de tipo do Python, com isso seu editor e ferramentas externas podem te dar um suporte melhor">anotada com tipos</dfn>.
* Usado para aplicaçÔes em produção.
-## Recursos do Starlette { #starlette-features }
+## Funcionalidades do Starlette { #starlette-features }
**FastAPI** Ă© totalmente compatĂvel com (e baseado no) [**Starlette**](https://www.starlette.dev/). EntĂŁo, qualquer cĂłdigo adicional Starlette que vocĂȘ tiver, tambĂ©m funcionarĂĄ.
`FastAPI` Ă© na verdade uma sub-classe do `Starlette`. EntĂŁo, se vocĂȘ jĂĄ conhece ou usa Starlette, a maioria das funcionalidades se comportarĂĄ da mesma forma.
-Com **FastAPI**, vocĂȘ terĂĄ todos os recursos do **Starlette** (jĂĄ que FastAPI Ă© apenas um Starlette com esterĂłides):
+Com **FastAPI**, vocĂȘ terĂĄ todas as funcionalidades do **Starlette** (jĂĄ que FastAPI Ă© apenas um Starlette com esteroides):
* Desempenho realmente impressionante. Ă [um dos frameworks Python disponĂveis mais rĂĄpidos, a par com o **NodeJS** e **Go**](https://github.com/encode/starlette#performance).
* Suporte a **WebSocket**.
* Tarefas em processo background.
-* Eventos na inicialização e encerramento.
+* Eventos de inicialização e encerramento.
* Cliente de testes construĂdo sobre HTTPX.
-* Respostas em **CORS**, GZip, Static Files, Streaming.
+* Respostas **CORS**, GZip, Static Files, Streaming.
* Suporte a **Session e Cookie**.
* 100% de cobertura de testes.
-* 100% do código utilizando anotaçÔes de tipo.
+* Base de código 100% com anotaçÔes de tipo.
-## Recursos do Pydantic { #pydantic-features }
+## Funcionalidades do Pydantic { #pydantic-features }
**FastAPI** Ă© totalmente compatĂvel com (e baseado no) [**Pydantic**](https://docs.pydantic.dev/). EntĂŁo, qualquer cĂłdigo Pydantic adicional que vocĂȘ tiver, tambĂ©m funcionarĂĄ.
O mesmo se aplica no sentido inverso, em muitos casos vocĂȘ poderĂĄ simplesmente passar o objeto que vocĂȘ recebeu do banco de dados **diretamente para o cliente**.
-Com **FastAPI** vocĂȘ terĂĄ todos os recursos do **Pydantic** (jĂĄ que FastAPI utiliza o Pydantic para todo o controle dos dados):
+Com **FastAPI** vocĂȘ terĂĄ todas as funcionalidades do **Pydantic** (jĂĄ que FastAPI utiliza o Pydantic para todo o controle dos dados):
* **Sem pegadinhas**:
* Sem novas definiçÔes de esquema de micro-linguagem para aprender.
## Acompanhe o repositório no GitHub para lançamentos { #watch-the-github-repository-for-releases }
-VocĂȘ pode âacompanharâ (watch) o FastAPI no GitHub (clicando no botĂŁo âwatchâ no canto superior direito): [https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi). đ
+VocĂȘ pode âacompanharâ o FastAPI no GitHub (clicando no botĂŁo âwatchâ no canto superior direito): [https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi). đ
LĂĄ vocĂȘ pode selecionar âApenas lançamentosâ.
# Configure a UI do Swagger { #configure-swagger-ui }
+
VocĂȘ pode configurar alguns [parĂąmetros extras da UI do Swagger](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/).
Para configurå-los, passe o argumento `swagger_ui_parameters` ao criar o objeto da aplicação `FastAPI()` ou para a função `get_swagger_ui_html()`.
Isso é um recurso "avançado".
-Se vocĂȘ for um iniciante em **FastAPI** vocĂȘ deve considerar pular essa seção.
+Se vocĂȘ estĂĄ apenas começando com **FastAPI**, talvez queira pular esta seção.
///
Se não houver `gzip` no cabeçalho, ele não tentarå descomprimir o corpo.
-Dessa forma, a mesma classe de rota pode lidar com requisiçÔes comprimidas ou não comprimidas.
+Dessa forma, a mesma classe de rota pode lidar com requisiçÔes comprimidas com gzip ou não comprimidas.
{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[9:16] *}
Para resolver esse mesmo problema, Ă© provavelmente muito mais fĂĄcil usar o `body` em um manipulador personalizado para `RequestValidationError` ([Tratando Erros](../tutorial/handling-errors.md#use-the-requestvalidationerror-body)).
-Mas esse exemplo ainda Ă© valido e mostra como interagir com os componentes internos.
+Mas esse exemplo ainda Ă© vĂĄlido e mostra como interagir com os componentes internos.
///
# GraphQL { #graphql }
+
Como o **FastAPI** Ă© baseado no padrĂŁo **ASGI**, Ă© muito fĂĄcil integrar qualquer biblioteca **GraphQL** tambĂ©m compatĂvel com ASGI.
VocĂȘ pode combinar *operaçÔes de rota* normais do FastAPI com GraphQL na mesma aplicação.
O FastAPI 0.126.0 removeu o suporte ao Pydantic v1, enquanto ainda oferece suporte a `pydantic.v1` por mais algum tempo.
+O FastAPI 0.128.0 também removeu o suporte a `pydantic.v1`, então as versÔes mais recentes do FastAPI exigem o Pydantic v2.
+
/// warning | Atenção
A equipe do Pydantic interrompeu o suporte ao Pydantic v1 para as versÔes mais recentes do Python, a partir do **Python 3.14**.
### Suporte do FastAPI ao Pydantic v1 no v2 { #fastapi-support-for-pydantic-v1-in-v2 }
+/// warning | Atenção
+
+Este suporte do FastAPI para modelos `pydantic.v1` foi adicionado no **FastAPI 0.119.0** e removido no **FastAPI 0.128.0**. Ele foi pensado como uma ajuda temporåria para a migração para o Pydantic v2.
+
+Nas versÔes atuais do FastAPI, usar um modelo `pydantic.v1` na sua aplicação gerarå um erro.
+
+O restante desta seção descreve o suporte temporĂĄrio disponĂvel apenas nessas versĂ”es antigas.
+
+///
+
Desde o FastAPI 0.119.0, hå também suporte parcial ao Pydantic v1 a partir de dentro do Pydantic v2, para facilitar a migração para o v2.
Assim, vocĂȘ pode atualizar o Pydantic para a versĂŁo 2 mais recente e alterar os imports para usar o submĂłdulo `pydantic.v1`, e em muitos casos tudo simplesmente funcionarĂĄ.
### Migre em etapas { #migrate-in-steps }
+/// warning | Atenção
+
+A migração gradual usando modelos Pydantic v1 e v2 na mesma aplicação descrita abaixo só funciona do **FastAPI 0.119.0 ao 0.127.x**. Ela foi removida no **FastAPI 0.128.0**, e as versÔes mais recentes exigem modelos **Pydantic v2**.
+
+///
+
/// tip | Dica
Primeiro tente com o `bump-pydantic`, se seus testes passarem e isso funcionar, entĂŁo vocĂȘ concluiu tudo com um Ășnico comando. âš
# Esquemas OpenAPI Separados para Entrada e SaĂda ou NĂŁo { #separate-openapi-schemas-for-input-and-output-or-not }
+
Desde que o **Pydantic v2** foi lançado, o OpenAPI gerado Ă© um pouco mais exato e **correto** do que antes. đ
De fato, em alguns casos, ele terĂĄ atĂ© **dois JSON Schemas** no OpenAPI para o mesmo modelo Pydantic, para entrada e saĂda, dependendo se eles possuem **valores padrĂŁo**.
---
-FastAPI é um framework web moderno e råpido (alta performance) para construção de APIs com Python, baseado nos type hints padrÔes do Python.
+FastAPI é um framework web moderno e råpido (alta performance) para construção de APIs com Python, baseado nas anotaçÔes de tipo padrão do Python.
Os recursos chave sĂŁo:
* **RĂĄpido para codar**: Aumenta a velocidade para desenvolver recursos entre 200% a 300%. *
* **Poucos bugs**: Reduz cerca de 40% de erros induzidos por humanos (desenvolvedores). *
* **Intuitivo**: Grande suporte a editores. <dfn title="também conhecido como: autocompletar, preenchimento automåtico, IntelliSense">Completação</dfn> em todos os lugares. Menos tempo debugando.
-* **FĂĄcil**: Projetado para ser fĂĄcil de aprender e usar. Menos tempo lendo docs.
+* **Fåcil**: Projetado para ser fåcil de aprender e usar. Menos tempo lendo documentação.
* **Enxuto**: Minimize duplicação de cĂłdigo. MĂșltiplas funcionalidades para cada declaração de parĂąmetro. Menos bugs.
* **Robusto**: Tenha código pronto para produção. E com documentação interativa automåtica.
* **Baseado em padrĂ”es**: Baseado em (e totalmente compatĂvel com) os padrĂ”es abertos para APIs: [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (anteriormente conhecido como Swagger) e [JSON Schema](https://json-schema.org/).
**Nota**:
-Se vocĂȘ nĂŁo sabe, verifique a seção _"Com pressa?"_ sobre [`async` e `await` nas docs](https://fastapi.tiangolo.com/pt/async/#in-a-hurry).
+Se vocĂȘ nĂŁo sabe, verifique a seção _"Com pressa?"_ sobre [`async` e `await` na documentação](https://fastapi.tiangolo.com/pt/async/#in-a-hurry).
</details>
# Full Stack FastAPI Template { #full-stack-fastapi-template }
-_Templates_, embora tipicamente venham com alguma configuração especĂfica, sĂŁo desenhados para serem flexĂveis e customizĂĄveis. Isso permite que vocĂȘ os modifique e adapte para as especificaçÔes do seu projeto, fazendo-os um excelente ponto de partida. đ
+Templates, embora tipicamente venham com alguma configuração especĂfica, sĂŁo desenhados para serem flexĂveis e customizĂĄveis. Isso permite que vocĂȘ os modifique e adapte para as especificaçÔes do seu projeto, fazendo-os um excelente ponto de partida. đ
-VocĂȘ pode usar esse _template_ para começar, jĂĄ que ele inclui vĂĄrias configuraçÔes iniciais, segurança, banco de dados, e alguns _endpoints_ de API jĂĄ feitos para vocĂȘ.
+VocĂȘ pode usar esse template para começar, jĂĄ que ele inclui vĂĄrias configuraçÔes iniciais, segurança, banco de dados e alguns endpoints de API jĂĄ feitos para vocĂȘ.
RepositĂłrio GitHub: [Full Stack FastAPI Template](https://github.com/tiangolo/full-stack-fastapi-template)
## Full Stack FastAPI Template - Pilha de Tecnologias e Recursos { #full-stack-fastapi-template-technology-stack-and-features }
- ⥠[**FastAPI**](https://fastapi.tiangolo.com/pt) para a API do backend em Python.
- - 𧰠[SQLModel](https://sqlmodel.tiangolo.com) para as interaçÔes do Python com bancos de dados SQL (ORM).
- - đ [Pydantic](https://docs.pydantic.dev), usado pelo FastAPI, para validação de dados e gerenciamento de configuraçÔes.
- - đŸ [PostgreSQL](https://www.postgresql.org) como banco de dados SQL.
+ - 𧰠[SQLModel](https://sqlmodel.tiangolo.com) para as interaçÔes do Python com bancos de dados SQL (ORM).
+ - đ [Pydantic](https://docs.pydantic.dev), usado pelo FastAPI, para validação de dados e gerenciamento de configuraçÔes.
+ - đŸ [PostgreSQL](https://www.postgresql.org) como banco de dados SQL.
- đ [React](https://react.dev) para o frontend.
- - đ Usando TypeScript, hooks, Vite, e outras partes de uma _stack_ frontend moderna.
- - đš [Tailwind CSS](https://tailwindcss.com) e [shadcn/ui](https://ui.shadcn.com) para os componentes de frontend.
- - đ€ Um cliente frontend automaticamente gerado.
- - đ§Ș [Playwright](https://playwright.dev) para testes Ponta-a-Ponta.
- - đŠ Suporte para modo escuro.
+ - đ Usando TypeScript, hooks, Vite, e outras partes de uma stack frontend moderna.
+ - đš [Tailwind CSS](https://tailwindcss.com) e [shadcn/ui](https://ui.shadcn.com) para os componentes de frontend.
+ - đ€ Um cliente frontend automaticamente gerado.
+ - đ§Ș [Playwright](https://playwright.dev) para testes Ponta-a-Ponta.
+ - đŠ Suporte para modo escuro.
- đ [Docker Compose](https://www.docker.com) para desenvolvimento e produção.
- đ Hash seguro de senhas por padrĂŁo.
- đ Autenticação JWT (JSON Web Token).
- â
Testes com [Pytest](https://pytest.org).
- đ [Traefik](https://traefik.io) como proxy reverso / balanceador de carga.
- đą InstruçÔes de deployment usando Docker Compose, incluindo como configurar um proxy frontend com Traefik para gerenciar automaticamente certificados HTTPS.
-- đ CI (Integração ContĂnua) e CD (_Deploy_ ContĂnuo) baseado em GitHub Actions.
+- đ CI (integração contĂnua) e CD (deployment contĂnuo) baseados em GitHub Actions.
# Introdução aos tipos Python { #python-types-intro }
-O Python possui suporte para "type hints" opcionais (também chamados de "type annotations").
+O Python possui suporte para "anotaçÔes de tipo" opcionais (também chamadas de "type annotations").
-Esses **"type hints"** ou anotaçÔes são uma sintaxe especial que permite declarar o <dfn title="por exemplo: str, int, float, bool">tipo</dfn> de uma variåvel.
+Essas **"anotaçÔes de tipo"** ou anotaçÔes são uma sintaxe especial que permite declarar o <dfn title="por exemplo: str, int, float, bool">tipo</dfn> de uma variåvel.
Ao declarar tipos para suas variĂĄveis, editores e ferramentas podem oferecer um melhor suporte.
-Este Ă© apenas um **tutorial rĂĄpido / atualização** sobre type hints do Python. Ele cobre apenas o mĂnimo necessĂĄrio para usĂĄ-los com o **FastAPI**... que Ă© realmente muito pouco.
+Este Ă© apenas um **tutorial rĂĄpido / atualização** sobre anotaçÔes de tipo do Python. Ele cobre apenas o mĂnimo necessĂĄrio para usĂĄ-las com o **FastAPI**... que Ă© realmente muito pouco.
-O **FastAPI** Ă© todo baseado nesses type hints, eles oferecem muitas vantagens e benefĂcios.
+O **FastAPI** Ă© todo baseado nessas anotaçÔes de tipo, elas oferecem muitas vantagens e benefĂcios.
-Mas mesmo que vocĂȘ nunca use o **FastAPI**, vocĂȘ se beneficiaria de aprender um pouco sobre eles.
+Mas mesmo que vocĂȘ nunca use o **FastAPI**, vocĂȘ se beneficiaria de aprender um pouco sobre elas.
/// note | Nota
-Se vocĂȘ Ă© um especialista em Python e jĂĄ sabe tudo sobre type hints, pule para o prĂłximo capĂtulo.
+Se vocĂȘ Ă© um especialista em Python e jĂĄ sabe tudo sobre anotaçÔes de tipo, pule para o prĂłximo capĂtulo.
///
* Pega um `first_name` e `last_name`.
* Converte a primeira letra de cada uma em maiĂșsculas com `title()`.
-* <dfn title="Coloca-os juntos, como um sĂł. Com o conteĂșdo de um apĂłs o outro.">Concatena</dfn> com um espaço no meio.
+* <dfn title="Coloca-os juntos, como um sĂł. Com o conteĂșdo de um apĂłs o outro.">Concatena</dfn>-os com um espaço no meio.
{* ../../docs_src/python_types/tutorial001_py310.py hl[2] *}
Mas agora imagine que vocĂȘ estava escrevendo do zero.
-Em algum momento vocĂȘ teria iniciado a definição da função, jĂĄ tinha os parĂąmetros prontos...
+Em algum momento vocĂȘ começa a definir a função, e jĂĄ tem os parĂąmetros prontos...
-Mas entĂŁo vocĂȘ deve chamar "esse mĂ©todo que converte a primeira letra em maiĂșscula".
+Mas entĂŁo vocĂȘ tem que chamar "esse mĂ©todo que converte a primeira letra em maiĂșscula".
Era `upper`? Era `uppercase`? `first_uppercase`? `capitalize`?
-Em seguida, tente com o velho amigo do programador, o preenchimento automĂĄtico do editor.
+EntĂŁo, vocĂȘ tenta com o velho amigo do programador, o preenchimento automĂĄtico do editor.
-VocĂȘ digita o primeiro parĂąmetro da função, `first_name`, depois um ponto (`.`) e, em seguida, pressiona `Ctrl+Space` para acionar o preenchimento automĂĄtico.
+VocĂȘ digita o primeiro parĂąmetro da função, `first_name`, depois um ponto (`.`) e, em seguida, pressiona `Ctrl+Space` para acionar o preenchimento.
Mas, infelizmente, vocĂȘ nĂŁo obtĂ©m nada Ăștil:
Ă isso aĂ.
-Esses sĂŁo os "type hints":
+Essas são as "anotaçÔes de tipo":
{* ../../docs_src/python_types/tutorial002_py310.py hl[1] *}
Estamos usando dois pontos (`:`), nĂŁo sinal de igual (`=`).
-E adicionar type hints normalmente nĂŁo muda o que acontece do que aconteceria sem eles.
+E adicionar anotaçÔes de tipo normalmente não muda o que acontece do que aconteceria sem elas.
-Mas agora, imagine que vocĂȘ estĂĄ novamente no meio da criação dessa função, mas com type hints.
+Mas agora, imagine que vocĂȘ estĂĄ novamente no meio da criação dessa função, mas com anotaçÔes de tipo.
-No mesmo ponto, vocĂȘ tenta acionar o preenchimento automĂĄtico com o `Ctrl+Space` e vĂȘ:
+No mesmo ponto, vocĂȘ tenta acionar o autocompletar com `Ctrl+Space` e vĂȘ:
<img src="/img/python-types/image02.png">
## Mais motivação { #more-motivation }
-Verifique esta função, ela jå possui type hints:
+Verifique esta função, ela jå possui anotaçÔes de tipo:
{* ../../docs_src/python_types/tutorial003_py310.py hl[1] *}
-Como o editor conhece os tipos das variĂĄveis, vocĂȘ nĂŁo obtĂ©m apenas o preenchimento automĂĄtico, mas tambĂ©m as verificaçÔes de erro:
+Como o editor conhece os tipos das variĂĄveis, vocĂȘ nĂŁo obtĂ©m apenas o preenchimento, mas tambĂ©m as verificaçÔes de erro:
<img src="/img/python-types/image04.png">
## Declarando tipos { #declaring-types }
-VocĂȘ acabou de ver o local principal para declarar type hints. Como parĂąmetros de função.
+VocĂȘ acabou de ver o local principal para declarar anotaçÔes de tipo. Como parĂąmetros de função.
-Este tambĂ©m Ă© o principal local em que vocĂȘ os usaria com o **FastAPI**.
+Este tambĂ©m Ă© o principal local em que vocĂȘ as usaria com o **FastAPI**.
### Tipos simples { #simple-types }
### MĂłdulo `typing` { #typing-module }
-Para alguns casos adicionais, vocĂȘ pode precisar importar alguns itens do mĂłdulo padrĂŁo `typing`, por exemplo, quando quiser declarar que algo pode ter "qualquer tipo", vocĂȘ pode usar `Any` de `typing`:
+Para alguns casos de uso adicionais, vocĂȘ pode precisar importar alguns itens do mĂłdulo padrĂŁo `typing`, por exemplo, quando quiser declarar que algo pode ter "qualquer tipo", vocĂȘ pode usar `Any` de `typing`:
```python
from typing import Any
### Tipos genéricos { #generic-types }
-Alguns tipos podem receber "parĂąmetros de tipo" entre colchetes, para definir seus tipos internos, por exemplo, uma "lista de strings" seria declarada como `list[str]`.
+Alguns tipos podem receber "parĂąmetros de tipo" entre colchetes, para definir seus tipos internos, por exemplo, uma "list de strings" seria declarada como `list[str]`.
Esses tipos que podem receber parùmetros de tipo são chamados **tipos genéricos** ou **genéricos**.
-VocĂȘ pode usar os mesmos tipos internos como genĂ©ricos (com colchetes e tipos dentro):
+VocĂȘ pode usar os mesmos tipos embutidos como genĂ©ricos (com colchetes e tipos dentro):
* `list`
* `tuple`
Como o tipo, coloque `list`.
-Como a lista Ă© um tipo que contĂ©m tipos internos, vocĂȘ os coloca entre colchetes:
+Como a list Ă© um tipo que contĂ©m alguns tipos internos, vocĂȘ os coloca entre colchetes:
{* ../../docs_src/python_types/tutorial006_py310.py hl[1] *}
///
-Isso significa: "a variĂĄvel `items` Ă© uma `list`, e cada um dos itens desta lista Ă© uma `str`".
+Isso significa: "a variĂĄvel `items` Ă© uma `list`, e cada um dos itens desta list Ă© uma `str`".
-Ao fazer isso, seu editor pode fornecer suporte mesmo durante o processamento de itens da lista:
+Ao fazer isso, seu editor pode fornecer suporte mesmo durante o processamento de itens da list:
<img src="/img/python-types/image05.png">
Sem tipos, isso Ă© quase impossĂvel de alcançar.
-Observe que a variĂĄvel `item` Ă© um dos elementos da lista `items`.
+Observe que a variĂĄvel `item` Ă© um dos elementos da list `items`.
E, ainda assim, o editor sabe que Ă© um `str` e fornece suporte para isso.
{* ../../docs_src/python_types/tutorial008_py310.py hl[1] *}
-Isso significa que:
+Isso significa:
* A variĂĄvel `prices` Ă© um `dict`:
* As chaves deste `dict` sĂŁo do tipo `str` (digamos, o nome de cada item).
E cada atributo tem um tipo.
-Em seguida, vocĂȘ cria uma instĂąncia dessa classe com alguns valores e ela os validarĂĄ, os converterĂĄ para o tipo apropriado (se for esse o caso) e fornecerĂĄ um objeto com todos os dados.
+Em seguida, vocĂȘ cria uma instĂąncia dessa classe com alguns valores e ela validarĂĄ os valores, os converterĂĄ para o tipo apropriado (se for esse o caso) e fornecerĂĄ um objeto com todos os dados.
E vocĂȘ recebe todo o suporte do editor com esse objeto resultante.
/// note | Nota
-Para saber mais sobre o [Pydantic, verifique a documentação](https://docs.pydantic.dev/).
+Para saber mais sobre [Pydantic, verifique a documentação](https://docs.pydantic.dev/).
///
VocĂȘ verĂĄ muito mais disso na prĂĄtica no [Tutorial - Guia do usuĂĄrio](tutorial/index.md).
-## Type Hints com Metadados de AnotaçÔes { #type-hints-with-metadata-annotations }
+## AnotaçÔes de Tipo com AnotaçÔes de Metadados { #type-hints-with-metadata-annotations }
-O Python também possui uma funcionalidade que permite incluir **<dfn title="InformaçÔes sobre os dados, neste caso, informaçÔes sobre o tipo, por exemplo, uma descrição.">metadados</dfn> adicionais** nesses type hints utilizando `Annotated`.
+O Python também possui uma funcionalidade que permite incluir **<dfn title="Dados sobre os dados, neste caso, informaçÔes sobre o tipo, por exemplo, uma descrição.">metadados</dfn> adicionais** nessas anotaçÔes de tipo utilizando `Annotated`.
VocĂȘ pode importar `Annotated` de `typing`.
Mas vocĂȘ pode utilizar este espaço dentro do `Annotated` para fornecer ao **FastAPI** metadados adicionais sobre como vocĂȘ deseja que a sua aplicação se comporte.
-O importante aqui de se lembrar Ă© que **o primeiro *type parameter*** que vocĂȘ informar ao `Annotated` Ă© o **tipo de fato**. O resto Ă© apenas metadado para outras ferramentas.
+O importante aqui de se lembrar Ă© que **o primeiro *parĂąmetro de tipo*** que vocĂȘ informar ao `Annotated` Ă© o **tipo de fato**. O resto Ă© apenas metadados para outras ferramentas.
Por hora, vocĂȘ precisa apenas saber que o `Annotated` existe, e que ele Ă© Python padrĂŁo. đ
///
-## Type hints no **FastAPI** { #type-hints-in-fastapi }
+## AnotaçÔes de tipo no **FastAPI** { #type-hints-in-fastapi }
-O **FastAPI** aproveita esses type hints para fazer vĂĄrias coisas.
+O **FastAPI** aproveita essas anotaçÔes de tipo para fazer vårias coisas.
-Com o **FastAPI**, vocĂȘ declara parĂąmetros com type hints e obtĂ©m:
+Com o **FastAPI**, vocĂȘ declara parĂąmetros com anotaçÔes de tipo e obtĂ©m:
* **Suporte ao editor**.
* **VerificaçÔes de tipo**.
```
.
âââ app
-â  âââ __init__.py
-â  âââ main.py
-â  âââ dependencies.py
-â  âââ routers
-â  â âââ __init__.py
-â  â âââ items.py
-â  â âââ users.py
-â  âââ internal
-â  âââ __init__.py
-â  âââ admin.py
+â âââ __init__.py
+â âââ main.py
+â âââ dependencies.py
+â âââ routers
+â â âââ __init__.py
+â â âââ items.py
+â â âââ users.py
+â âââ internal
+â âââ __init__.py
+â âââ admin.py
```
/// tip | Dica
{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[10:11] title["app/main.py"] *}
-/// note | Detalhes TĂ©cnicos
+/// note | Nota
-O FastAPI mantĂ©m o `APIRouter` original e seus `APIRoute`s ativos quando o router Ă© incluĂdo na aplicação principal.
+`users.router` contém o `APIRouter` dentro do arquivo `app/routers/users.py`.
-Isso significa que subclasses personalizadas de `APIRouter` e `APIRoute` ainda podem participar depois que o router Ă© incluĂdo.
+E `items.router` contém o `APIRouter` dentro do arquivo `app/routers/items.py`.
///
Ele incluirĂĄ todas as rotas daquele router como parte dele.
+/// note | Detalhes TĂ©cnicos
+
+O FastAPI mantĂ©m o `APIRouter` original e seus `APIRoute`s ativos quando o router Ă© incluĂdo na aplicação principal.
+
+Isso significa que subclasses personalizadas de `APIRouter` e `APIRoute` ainda podem participar depois que o router Ă© incluĂdo.
+
+///
+
/// tip | Dica
VocĂȘ nĂŁo precisa se preocupar com desempenho ao incluir routers.
{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
-Isso farĂĄ com que tags seja uma lista de itens mesmo sem declarar o tipo dos elementos desta lista.
+Isso farĂĄ com que `tags` seja uma lista, mesmo sem declarar o tipo dos elementos desta lista.
## Campos do tipo Lista com um parĂąmetro de tipo { #list-fields-with-type-parameter }
Mas esse tipo pode ser outro modelo Pydantic.
-Portanto, vocĂȘ pode declarar "objects" JSON profundamente aninhados com nomes, tipos e validaçÔes de atributos especĂficos.
+Portanto, vocĂȘ pode declarar "objetos" JSON profundamente aninhados com nomes, tipos e validaçÔes de atributos especĂficos.
Tudo isso, aninhado arbitrariamente.
{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}
-Isso significa que o **FastAPI** vai esperar um corpo similar Ă :
+Isso significa que o **FastAPI** vai esperar um corpo similar a:
```JSON
{
Para ver todas as opçÔes possĂveis, consulte a [VisĂŁo geral dos tipos do Pydantic](https://docs.pydantic.dev/latest/concepts/types/). VocĂȘ verĂĄ alguns exemplos no prĂłximo capĂtulo.
-Por exemplo, no modelo `Image` nós temos um campo `url`, nós podemos declarå-lo como um `HttpUrl` do Pydantic invés de como uma `str`:
+Por exemplo, no modelo `Image` nĂłs temos um campo `url`, nĂłs podemos declarĂĄ-lo como um `HttpUrl` do Pydantic em vez de como uma `str`:
{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}
-A string serĂĄ verificada para se tornar uma URL vĂĄlida e documentada no JSON Schema / OpenAPI como tal.
+A string serĂĄ verificada para ser uma URL vĂĄlida e documentada no JSON Schema / OpenAPI como tal.
## Atributos como listas de submodelos { #attributes-with-lists-of-submodels }
## Corpos de listas puras { #bodies-of-pure-lists }
-Se o valor de primeiro nĂvel do corpo JSON que vocĂȘ espera for um `array` do JSON (uma` lista` do Python), vocĂȘ pode declarar o tipo no parĂąmetro da função, da mesma forma que nos modelos do Pydantic:
+Se o valor de primeiro nĂvel do corpo JSON que vocĂȘ espera for um `array` do JSON (uma `list` do Python), vocĂȘ pode declarar o tipo no parĂąmetro da função, da mesma forma que nos modelos do Pydantic:
```Python
images: list[Image]
---
-Outro caso Ăștil Ă© quando vocĂȘ deseja ter chaves de outro tipo, por exemplo, `int`.
+Outro caso Ăștil Ă© quando vocĂȘ deseja ter chaves de outro tipo (por exemplo, `int`).
Ă isso que vamos ver aqui.
-Neste caso, vocĂȘ aceitaria qualquer `dict`, desde que tenha chaves` int` com valores `float`:
+Neste caso, vocĂȘ aceitaria qualquer `dict`, desde que tenha chaves `int` com valores `float`:
{* ../../docs_src/body_nested_models/tutorial009_py310.py hl[7] *}
Isso significa que, embora os clientes da API sĂł possam enviar strings como chaves, desde que essas strings contenham inteiros puros, o Pydantic irĂĄ convertĂȘ-los e validĂĄ-los.
-E o `dict` que vocĂȘ recebe como `weights` terĂĄ, na verdade, chaves `int` e valores` float`.
+E o `dict` que vocĂȘ recebe como `weights` terĂĄ, na verdade, chaves `int` e valores `float`.
///
Mas com todos os benefĂcios:
* Suporte do editor (preenchimento automĂĄtico em todo canto!)
-* Conversão de dados (parsing/serialização)
+* Conversão de dados (também conhecido como parsing / serialização)
* Validação de dados
* Documentação dos esquemas
* Documentação automåtica
# Corpo da requisição { #request-body }
+
Quando vocĂȘ precisa enviar dados de um cliente (como de um navegador) para sua API, vocĂȘ os envia como um **corpo da requisição**.
O corpo da **requisição** é a informação enviada pelo cliente para sua API. O corpo da **resposta** é a informação que sua API envia para o cliente.
---
-Se vocĂȘ usar o Pycharm, vocĂȘ pode:
+Se vocĂȘ usar o PyCharm, vocĂȘ pode:
* Abrir o menu "Executar".
* Selecionar a opção "Depurar...".
## DependĂȘncias com `yield` e `except` { #dependencies-with-yield-and-except }
-Se vocĂȘ capturar uma exceção com `except` em uma dependĂȘncia que utilize `yield` e ela nĂŁo for levantada novamente (ou uma nova exceção for levantada), o FastAPI nĂŁo serĂĄ capaz de identificar que houve uma exceção, da mesma forma que aconteceria com Python puro:
+Se vocĂȘ capturar uma exceção com `except` em uma dependĂȘncia que utilize `yield` e nĂŁo a levantar novamente (nem levantar uma nova exceção), o FastAPI nĂŁo serĂĄ capaz de identificar que houve uma exceção, da mesma forma que aconteceria com Python puro:
{* ../../docs_src/dependencies/tutorial008c_an_py310.py hl[15:16] *}
### Sempre `raise` em DependĂȘncias com `yield` e `except` { #always-raise-in-dependencies-with-yield-and-except }
-Se vocĂȘ capturar uma exceção em uma dependĂȘncia com `yield`, a menos que vocĂȘ esteja levantando outra `HTTPException` ou coisa parecida, **vocĂȘ deve relançar a exceção original**.
+Se vocĂȘ capturar uma exceção em uma dependĂȘncia com `yield`, a menos que vocĂȘ esteja levantando outra `HTTPException` ou coisa parecida, **vocĂȘ deveria relançar a exceção original**.
VocĂȘ pode relançar a mesma exceção utilizando `raise`:
`Depends()` recebe um parĂąmetro `scope` que pode ser:
-* `"function"`: iniciar a dependĂȘncia antes da *função de operação de rota* que trata a requisição, encerrar a dependĂȘncia depois que a *função de operação de rota* termina, mas **antes** de a resposta ser enviada de volta ao cliente. Assim, a função da dependĂȘncia serĂĄ executada **em torno** da *função de operação de rota*.
+* `"function"`: iniciar a dependĂȘncia antes da *função de operação de rota* que trata a requisição, encerrar a dependĂȘncia depois que a *função de operação de rota* termina, mas **antes** de a resposta ser enviada de volta ao cliente. Assim, a função da dependĂȘncia serĂĄ executada **em torno** da ***função*** *de operação de rota*.
* `"request"`: iniciar a dependĂȘncia antes da *função de operação de rota* que trata a requisição (semelhante a quando se usa `"function"`), mas encerrar **depois** que a resposta Ă© enviada de volta ao cliente. Assim, a função da dependĂȘncia serĂĄ executada **em torno** do ciclo de **requisição** e resposta.
Se nĂŁo for especificado e a dependĂȘncia tiver `yield`, ela terĂĄ `scope` igual a `"request"` por padrĂŁo.
DependĂȘncias com `yield` evoluĂram ao longo do tempo para cobrir diferentes casos de uso e corrigir alguns problemas.
Se vocĂȘ quiser ver o que mudou em diferentes versĂ”es do FastAPI, vocĂȘ pode ler mais sobre isso no guia avançado, em [DependĂȘncias Avançadas - DependĂȘncias com `yield`, `HTTPException`, `except` e Tarefas de Background](../../advanced/advanced-dependencies.md#dependencies-with-yield-httpexception-except-and-background-tasks).
+
## Gerenciadores de contexto { #context-managers }
### O que sĂŁo "Gerenciadores de Contexto" { #what-are-context-managers }
* `datetime.timedelta`:
* O `datetime.timedelta` do Python.
* Em requisiçÔes e respostas serå representado como um `float` de segundos totais.
- * O Pydantic também permite representå-lo como uma "codificação ISO 8601 diferença de tempo", [cheque a documentação para mais informaçÔes](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers).
+ * O Pydantic também permite representå-lo como uma "codificação de diferença de tempo ISO 8601", [veja a documentação para mais informaçÔes](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers).
* `frozenset`:
* Em requisiçÔes e respostas, serå tratado da mesma forma que um `set`:
- * Nas requisiçÔes, uma lista serå lida, eliminando duplicadas e convertendo-a em um `set`.
+ * Nas requisiçÔes, uma list serå lida, eliminando duplicadas e convertendo-a em um `set`.
* Nas respostas, o `set` serĂĄ convertido para uma `list`.
* O esquema gerado vai especificar que os valores do `set` sĂŁo Ășnicos (usando o `uniqueItems` do JSON Schema).
* `bytes`:
* O `bytes` padrĂŁo do Python.
- * Em requisiçÔes e respostas serå representado como uma `str`.
+ * Em requisiçÔes e respostas serå tratado como `str`.
* O esquema gerado vai especificar que Ă© uma `str` com o "formato" `binary`.
* `Decimal`:
* O `Decimal` padrĂŁo do Python.
- * Em requisiçÔes e respostas serå representado como um `float`.
+ * Em requisiçÔes e respostas, tratado da mesma forma que um `float`.
* VocĂȘ pode checar todos os tipos de dados vĂĄlidos do Pydantic aqui: [Tipos de dados do Pydantic](https://docs.pydantic.dev/latest/usage/types/types/).
## Exemplo { #example }
Use vĂĄrios modelos Pydantic e herde livremente para cada caso.
-NĂŁo Ă© necessĂĄrio ter um Ășnico modelo de dados por entidade se essa entidade precisar ter diferentes "estados". No caso da "entidade" de usuĂĄrio com um estado que inclui `password`, `password_hash` e sem senha.
+NĂŁo Ă© necessĂĄrio ter um Ășnico modelo de dados por entidade se essa entidade precisar ter diferentes "estados". A "entidade" **usuĂĄrio** Ă© um exemplo, com estados que incluem `password`, `password_hash` ou sem senha.
### OpenAPI { #openapi }
-O **FastAPI** gera um "*schema*" com toda a sua API usando o padrĂŁo **OpenAPI** para definir APIs.
+O **FastAPI** gera um "schema" com toda a sua API usando o padrĂŁo **OpenAPI** para definir APIs.
-#### "*Schema*" { #schema }
+#### "Schema" { #schema }
-Um "*schema*" é uma definição ou descrição de algo. Não o código que o implementa, mas apenas uma descrição abstrata.
+Um "schema" é uma definição ou descrição de algo. Não o código que o implementa, mas apenas uma descrição abstrata.
-#### API "*schema*" { #api-schema }
+#### API "schema" { #api-schema }
-Nesse caso, [OpenAPI](https://github.com/OAI/OpenAPI-Specification) é uma especificação que determina como definir um *schema* da sua API.
+Nesse caso, [OpenAPI](https://github.com/OAI/OpenAPI-Specification) é uma especificação que determina como definir um schema da sua API.
-Esta definição de *schema* inclui os paths da sua API, os parĂąmetros possĂveis que eles usam, etc.
+Esta definição de schema inclui os paths da sua API, os parĂąmetros possĂveis que eles usam, etc.
-#### "*Schema*" de dados { #data-schema }
+#### "Schema" de dados { #data-schema }
-O termo "*schema*" tambĂ©m pode se referir Ă forma de alguns dados, como um conteĂșdo JSON.
+O termo "schema" tambĂ©m pode se referir Ă forma de alguns dados, como um conteĂșdo JSON.
Nesse caso, significaria os atributos JSON e os tipos de dados que eles possuem, etc.
#### OpenAPI e JSON Schema { #openapi-and-json-schema }
-OpenAPI define um *schema* de API para sua API. E esse *schema* inclui definiçÔes (ou "*schemas*") dos dados enviados e recebidos por sua API usando **JSON Schema**, o padrão para *schemas* de dados JSON.
+OpenAPI define um schema de API para sua API. E esse schema inclui definiçÔes (ou "schemas") dos dados enviados e recebidos por sua API usando **JSON Schema**, o padrão para schemas de dados JSON.
#### Verifique o `openapi.json` { #check-the-openapi-json }
-Se vocĂȘ estĂĄ curioso(a) sobre a aparĂȘncia do *schema* bruto OpenAPI, o FastAPI gera automaticamente um JSON (*schema*) com as descriçÔes de toda a sua API.
+Se vocĂȘ estĂĄ curioso(a) sobre a aparĂȘncia do schema bruto OpenAPI, o FastAPI gera automaticamente um JSON (schema) com as descriçÔes de toda a sua API.
VocĂȘ pode ver isso diretamente em: [http://127.0.0.1:8000/openapi.json](http://127.0.0.1:8000/openapi.json).
#### Para que serve o OpenAPI { #what-is-openapi-for }
-O *schema* OpenAPI é o que possibilita os dois sistemas de documentação interativos mostrados.
+O schema OpenAPI é o que possibilita os dois sistemas de documentação interativos mostrados.
E existem dezenas de alternativas, todas baseadas em OpenAPI. VocĂȘ pode facilmente adicionar qualquer uma dessas alternativas Ă sua aplicação criada com **FastAPI**.
-VocĂȘ tambĂ©m pode usĂĄ-lo para gerar cĂłdigo automaticamente para clientes que se comunicam com sua API. Por exemplo, aplicativos front-end, mĂłveis ou IoT.
+VocĂȘ tambĂ©m pode usĂĄ-lo para gerar cĂłdigo automaticamente para clientes que se comunicam com sua API. Por exemplo, aplicaçÔes frontend, mĂłveis ou IoT.
### Configure o `entrypoint` da aplicação em `pyproject.toml` { #configure-the-app-entrypoint-in-pyproject-toml }
Este serå o principal ponto de interação para criar toda a sua API.
-### Passo 3: crie uma operação de rota { #step-3-create-a-path-operation }
+### Passo 3: crie uma *operação de rota* { #step-3-create-a-path-operation }
#### Path { #path }
Vamos chamå-los de "**operaçÔes**" também.
-#### Defina um decorador de operação de rota { #define-a-path-operation-decorator }
+#### Defina um *decorador de operação de rota* { #define-a-path-operation-decorator }
{* ../../docs_src/first_steps/tutorial001_py310.py hl[6] *}
O `@app.get("/")` diz ao **FastAPI** que a função logo abaixo é responsåvel por tratar as requisiçÔes que vão para:
* o path `/`
-* usando uma <dfn title="um método HTTP GET"><code>get</code> operação</dfn>
+* usando uma <dfn title="um método HTTP GET">operação <code>get</code></dfn>
/// note | InformaçÔes sobre `@decorator`
VocĂȘ pode retornar um `dict`, `list` e valores singulares como `str`, `int`, etc.
-VocĂȘ tambĂ©m pode devolver modelos Pydantic ( vocĂȘ verĂĄ mais sobre isso mais tarde).
+VocĂȘ tambĂ©m pode retornar modelos Pydantic (vocĂȘ verĂĄ mais sobre isso mais tarde).
Existem muitos outros objetos e modelos que serĂŁo convertidos automaticamente para JSON (incluindo ORMs, etc). Tente usar seus favoritos, Ă© altamente provĂĄvel que jĂĄ sejam compatĂveis.
Pode ser que vocĂȘ precise comunicar ao cliente que:
-* O cliente não tem direitos para realizar aquela operação.
+* O cliente não tem privilégios suficientes para aquela operação.
* O cliente nĂŁo tem acesso aquele recurso.
-* O item que o cliente estĂĄ tentando acessar nĂŁo existe.
+* O item que o cliente estava tentando acessar nĂŁo existe.
* etc.
-Nesses casos, vocĂȘ normalmente retornaria um **HTTP status code** prĂłximo ao status code na faixa do status code **400** (do 400 ao 499).
+Nesses casos, vocĂȘ normalmente retornaria um **HTTP status code** na faixa de **400** (do 400 ao 499).
-Isso é bastante similar ao caso do HTTP status code 200 (do 200 ao 299). Esses "200" status codes significam que, de algum modo, houve sucesso na requisição.
+Isso Ă© similar aos status codes HTTP 200 (do 200 ao 299). Esses status codes "200" significam que, de algum modo, houve um "sucesso" na request.
Os status codes na faixa dos 400 significam que houve um erro por parte do cliente.
-VocĂȘ se lembra de todos aqueles erros (e piadas) a respeito do "**404 Not Found**"?
+VocĂȘ se lembra de todos aqueles erros **"404 Not Found"** (e piadas)?
## Use o `HTTPException` { #use-httpexception }
-Para retornar ao cliente *responses* HTTP com erros, use o `HTTPException`.
+Para retornar responses HTTP com erros ao cliente, use o `HTTPException`.
-### Import `HTTPException` { #import-httpexception }
+### Importe `HTTPException` { #import-httpexception }
{* ../../docs_src/handling_errors/tutorial001_py310.py hl[1] *}
-### Lance o `HTTPException` no seu cĂłdigo { #raise-an-httpexception-in-your-code }
+### Lance uma `HTTPException` no seu cĂłdigo { #raise-an-httpexception-in-your-code }
-`HTTPException`, ao fundo, nada mais é do que a conjunção entre uma exceção comum do Python e informaçÔes adicionais relevantes para APIs.
+`HTTPException` é uma exceção normal do Python com dados adicionais relevantes para APIs.
-E porque Ă© uma exceção do Python, vocĂȘ nĂŁo **retorna** (return) o `HTTPException`, vocĂȘ lança o (raise) no seu cĂłdigo.
+Como Ă© uma exceção do Python, vocĂȘ nĂŁo dĂĄ `return` nela, vocĂȘ dĂĄ `raise` nela.
-Isso tambĂ©m significa que, se vocĂȘ estĂĄ escrevendo uma função de utilidade, a qual vocĂȘ estĂĄ chamando dentro da sua função de operação de rota, e vocĂȘ lança o `HTTPException` dentro da função de utilidade, o resto do seu cĂłdigo nĂŁo serĂĄ executado dentro da função de operação de rota. Ao contrĂĄrio, o `HTTPException` irĂĄ finalizar a requisição no mesmo instante e enviarĂĄ o erro HTTP oriundo do `HTTPException` para o cliente.
+Isso tambĂ©m significa que, se vocĂȘ estĂĄ dentro de uma função de utilidade que estĂĄ chamando dentro da sua *função de operação de rota*, e lança a `HTTPException` dentro dessa função de utilidade, o restante do cĂłdigo na *função de operação de rota* nĂŁo serĂĄ executado, a request serĂĄ encerrada imediatamente e o erro HTTP da `HTTPException` serĂĄ enviado ao cliente.
O benefĂcio de lançar uma exceção em vez de retornar um valor ficarĂĄ mais evidente na seção sobre DependĂȘncias e Segurança.
-Neste exemplo, quando o cliente pede, na requisição, por um item cujo ID não existe, a exceção com o status code `404` é lançada:
+Neste exemplo, quando o cliente solicita um item por um ID que não existe, lance uma exceção com status code `404`:
{* ../../docs_src/handling_errors/tutorial001_py310.py hl[11] *}
### A response resultante { #the-resulting-response }
-Se o cliente faz uma requisição para `http://example.com/items/foo` (um `item_id` `"foo"`), esse cliente receberå um HTTP status code 200, e uma resposta JSON:
-
+Se o cliente solicita `http://example.com/items/foo` (um `item_id` `"foo"`), esse cliente receberĂĄ um status code HTTP 200 e uma response JSON de:
```JSON
{
}
```
-Mas se o cliente faz uma requisição para `http://example.com/items/bar` (ou seja, um nĂŁo existente `item_id "bar"`), esse cliente receberĂĄ um HTTP status code 404 (o erro "nĂŁo encontrado" â *not found error*), e uma resposta JSON:
+Mas se o cliente solicita `http://example.com/items/bar` (um `item_id` `"bar"` inexistente), esse cliente receberĂĄ um status code HTTP 404 (o erro "not found") e uma response JSON de:
```JSON
{
/// tip | Dica
-Quando vocĂȘ lançar um `HTTPException`, vocĂȘ pode passar qualquer valor convertĂvel em JSON como parĂąmetro de `detail`, e nĂŁo apenas `str`.
+Ao lançar uma `HTTPException`, vocĂȘ pode passar qualquer valor que possa ser convertido para JSON como parĂąmetro `detail`, nĂŁo apenas `str`.
+
+VocĂȘ pode passar um `dict`, uma `list`, etc.
-VocĂȘ pode passar um `dict` ou um `list`, etc.
-Esses tipos de dados sĂŁo manipulados automaticamente pelo **FastAPI** e convertidos em JSON.
+Eles sĂŁo manipulados automaticamente pelo **FastAPI** e convertidos para JSON.
///
## Adicione headers customizados { #add-custom-headers }
-HĂĄ certas situaçÔes em que Ă© bastante Ăștil poder adicionar headers customizados no HTTP error. Exemplo disso seria adicionar headers customizados para tipos de segurança.
+HĂĄ algumas situaçÔes em que Ă© Ăștil poder adicionar headers customizados ao erro HTTP. Por exemplo, para alguns tipos de segurança.
-VocĂȘ provavelmente nĂŁo precisarĂĄ utilizar esses headers diretamente no seu cĂłdigo.
+VocĂȘ provavelmente nĂŁo precisarĂĄ usar isso diretamente no seu cĂłdigo.
-Mas caso vocĂȘ precise, para um cenĂĄrio mais complexo, vocĂȘ pode adicionar headers customizados:
+Mas caso precise em um cenĂĄrio avançado, vocĂȘ pode adicionar headers customizados:
{* ../../docs_src/handling_errors/tutorial002_py310.py hl[14] *}
## Instale manipuladores de exceçÔes customizados { #install-custom-exception-handlers }
-VocĂȘ pode adicionar manipuladores de exceção customizados com [a mesma seção de utilidade de exceçÔes presentes no Starlette](https://www.starlette.dev/exceptions/).
+VocĂȘ pode adicionar manipuladores de exceção customizados com [as mesmas utilidades de exceção do Starlette](https://www.starlette.dev/exceptions/).
+
+Digamos que vocĂȘ tenha uma exceção customizada `UnicornException` que vocĂȘ (ou uma biblioteca que vocĂȘ usa) possa lançar com `raise`.
-Digamos que vocĂȘ tenha uma exceção customizada `UnicornException` que vocĂȘ (ou uma biblioteca que vocĂȘ use) precise lançar (`raise`).
+E vocĂȘ quer manipular essa exceção globalmente com o FastAPI.
-Nesse cenĂĄrio, se vocĂȘ precisa manipular essa exceção de modo global com o FastAPI, vocĂȘ pode adicionar um manipulador de exceção customizada com `@app.exception_handler()`.
+VocĂȘ poderia adicionar um manipulador de exceção customizado com `@app.exception_handler()`:
{* ../../docs_src/handling_errors/tutorial003_py310.py hl[5:7,13:18,24] *}
-Nesse cenĂĄrio, se vocĂȘ fizer uma requisição para `/unicorns/yolo`, a *operação de rota* vai lançar (`raise`) o `UnicornException`.
+Aqui, se vocĂȘ fizer uma request para `/unicorns/yolo`, a *operação de rota* vai lançar com `raise` uma `UnicornException`.
-Essa exceção serå manipulada, contudo, pelo `unicorn_exception_handler`.
+Mas ela serĂĄ manipulada pelo `unicorn_exception_handler`.
-Dessa forma vocĂȘ receberĂĄ um erro "limpo", com o HTTP status code `418` e um JSON com o conteĂșdo:
+Assim, vocĂȘ receberĂĄ um erro limpo, com um status code HTTP `418` e um conteĂșdo JSON de:
```JSON
{"message": "Oops! yolo did something. There goes a rainbow..."}
VocĂȘ tambĂ©m pode usar `from starlette.requests import Request` e `from starlette.responses import JSONResponse`.
-**FastAPI** disponibiliza o mesmo `starlette.responses` atravĂ©s do `fastapi.responses` por conveniĂȘncia ao desenvolvedor. Contudo, a maior parte das respostas disponĂveis vem diretamente do Starlette. O mesmo acontece com o `Request`.
+**FastAPI** fornece o mesmo `starlette.responses` como `fastapi.responses` apenas como uma conveniĂȘncia para vocĂȘ, a pessoa desenvolvedora. Mas a maior parte das responses disponĂveis vem diretamente do Starlette. O mesmo acontece com `Request`.
///
**FastAPI** tem alguns manipuladores padrão de exceçÔes.
-Esses manipuladores sĂŁo os responsĂĄveis por retornar o JSON padrĂŁo de respostas quando vocĂȘ lança (`raise`) o `HTTPException` e quando a requisição tem dados invĂĄlidos.
+Esses manipuladores sĂŁo responsĂĄveis por retornar as responses JSON padrĂŁo quando vocĂȘ lança com `raise` uma `HTTPException` e quando a request tem dados invĂĄlidos.
-VocĂȘ pode sobrescrever esses manipuladores de exceção com os seus prĂłprios manipuladores.
+VocĂȘ pode sobrescrever esses manipuladores de exceção com os seus prĂłprios.
-### Sobrescreva exceçÔes de validação da requisição { #override-request-validation-exceptions }
+### Sobrescreva exceçÔes de validação da request { #override-request-validation-exceptions }
-Quando a requisição contém dados invålidos, **FastAPI** internamente lança para o `RequestValidationError`.
+Quando uma request contém dados invålidos, **FastAPI** internamente lança um `RequestValidationError`.
E também inclui um manipulador de exceçÔes padrão para ele.
-Para sobrescrevĂȘ-lo, importe o `RequestValidationError` e use-o com o `@app.exception_handler(RequestValidationError)` para decorar o manipulador de exceçÔes.
+Para sobrescrevĂȘ-lo, importe o `RequestValidationError` e use-o com `@app.exception_handler(RequestValidationError)` para decorar o manipulador de exceçÔes.
O manipulador de exceçÔes receberå um `Request` e a exceção.
{* ../../docs_src/handling_errors/tutorial004_py310.py hl[2,14:19] *}
-Se vocĂȘ for ao `/items/foo`, em vez de receber o JSON padrĂŁo com o erro:
+Agora, se vocĂȘ for para `/items/foo`, em vez de receber o erro JSON padrĂŁo com:
```JSON
{
}
```
-vocĂȘ receberĂĄ a versĂŁo em texto:
+vocĂȘ receberĂĄ uma versĂŁo em texto, com:
```
Validation errors:
### Sobrescreva o manipulador de erro `HTTPException` { #override-the-httpexception-error-handler }
-Do mesmo modo, vocĂȘ pode sobrescrever o `HTTPException`.
+Do mesmo modo, vocĂȘ pode sobrescrever o manipulador de `HTTPException`.
-Por exemplo, vocĂȘ pode querer retornar uma *response* em *plain text* ao invĂ©s de um JSON para os seguintes erros:
+Por exemplo, vocĂȘ poderia querer retornar uma response em texto simples em vez de JSON para estes erros:
{* ../../docs_src/handling_errors/tutorial004_py310.py hl[3:4,9:11,25] *}
/// note | Detalhes TĂ©cnicos
-VocĂȘ pode usar `from starlette.responses import PlainTextResponse`.
+VocĂȘ tambĂ©m pode usar `from starlette.responses import PlainTextResponse`.
-**FastAPI** disponibiliza o mesmo `starlette.responses` como `fastapi.responses`, como conveniĂȘncia a vocĂȘ, desenvolvedor. Contudo, a maior parte das respostas disponĂveis vem diretamente do Starlette.
+**FastAPI** fornece o mesmo `starlette.responses` como `fastapi.responses` apenas como uma conveniĂȘncia para vocĂȘ, a pessoa desenvolvedora. Mas a maior parte das responses disponĂveis vem diretamente do Starlette.
///
Tenha em mente que o `RequestValidationError` contĂ©m as informaçÔes do nome do arquivo e da linha onde o erro de validação acontece, para que vocĂȘ possa mostrĂĄ-las nos seus logs com as informaçÔes relevantes, se quiser.
-Mas isso significa que, se vocĂȘ simplesmente convertĂȘ-lo para uma string e retornar essa informação diretamente, vocĂȘ pode acabar vazando um pouco de informação sobre o seu sistema; por isso, aqui o cĂłdigo extrai e mostra cada erro de forma independente.
+Mas isso significa que, se vocĂȘ simplesmente convertĂȘ-lo para uma string e retornar essa informação diretamente, vocĂȘ poderia acabar vazando um pouco de informação sobre o seu sistema; por isso, aqui o cĂłdigo extrai e mostra cada erro de forma independente.
///
### Use o body do `RequestValidationError` { #use-the-requestvalidationerror-body }
-O `RequestValidationError` contém o `body` que ele recebeu de dados invålidos.
+O `RequestValidationError` contém o `body` que ele recebeu com dados invålidos.
-VocĂȘ pode utilizĂĄ-lo enquanto desenvolve seu app para registrar o *body* e debugĂĄ-lo, e assim retornĂĄ-lo ao usuĂĄrio, etc.
+VocĂȘ poderia usĂĄ-lo enquanto desenvolve sua aplicação para registrar o body e depurĂĄ-lo, retornĂĄ-lo ao usuĂĄrio, etc.
{* ../../docs_src/handling_errors/tutorial005_py310.py hl[14] *}
-Tente enviar um item invĂĄlido como este:
+Agora tente enviar um item invĂĄlido como:
```JSON
{
}
```
-VocĂȘ receberĂĄ uma *response* informando-o de que os dados sĂŁo invĂĄlidos, e contendo o *body* recebido:
+VocĂȘ receberĂĄ uma response dizendo que os dados sĂŁo invĂĄlidos contendo o body recebido:
```JSON hl_lines="12-15"
{
}
```
-#### O `HTTPException` do FastAPI vs o `HTTPException` do Starlette { #fastapis-httpexception-vs-starlettes-httpexception }
+#### `HTTPException` do FastAPI vs `HTTPException` do Starlette { #fastapis-httpexception-vs-starlettes-httpexception }
-O **FastAPI** tem o seu prĂłprio `HTTPException`.
+**FastAPI** tem a sua prĂłpria `HTTPException`.
-E a classe de erro `HTTPException` do **FastAPI** herda da classe de erro do `HTTPException` do Starlette.
+E a classe de erro `HTTPException` do **FastAPI** herda da classe de erro `HTTPException` do Starlette.
-A Ășnica diferença Ă© que o `HTTPException` do **FastAPI** aceita qualquer dado que possa ser convertido em JSON para o campo `detail`, enquanto o `HTTPException` do Starlette aceita apenas strings para esse campo.
+A Ășnica diferença Ă© que a `HTTPException` do **FastAPI** aceita qualquer dado que possa ser convertido para JSON no campo `detail`, enquanto a `HTTPException` do Starlette aceita apenas strings para ele.
-Portanto, vocĂȘ pode continuar lançando o `HTTPException` do **FastAPI** normalmente no seu cĂłdigo.
+Portanto, vocĂȘ pode continuar lançando a `HTTPException` do **FastAPI** normalmente no seu cĂłdigo.
-PorĂ©m, quando vocĂȘ registrar um manipulador de exceção, vocĂȘ deve registrĂĄ-lo atravĂ©s do `HTTPException` do Starlette.
+Mas quando registrar um manipulador de exceção, vocĂȘ deveria registrĂĄ-lo para a `HTTPException` do Starlette.
-Dessa forma, se qualquer parte do código interno, extensão ou plug-in do Starlette lançar um `HTTPException` do Starlette, o seu manipulador poderå capturar e tratå-lo.
+Dessa forma, se qualquer parte do código interno do Starlette, ou uma extensão ou plug-in do Starlette, lançar uma `HTTPException` do Starlette, seu manipulador poderå capturå-la e tratå-la.
-Neste exemplo, para poder ter ambos os `HTTPException` no mesmo código, a exceção do Starlette é renomeada para `StarletteHTTPException`:
+Neste exemplo, para poder ter ambas as `HTTPException`s no mesmo código, a exceção do Starlette é renomeada para `StarletteHTTPException`:
```Python
from starlette.exceptions import HTTPException as StarletteHTTPException
### Reutilize os manipuladores de exceção do **FastAPI** { #reuse-fastapis-exception-handlers }
-Se vocĂȘ quer usar a exceção em conjunto com o mesmo manipulador de exceção *default* do **FastAPI**, vocĂȘ pode importar e re-usar esses manipuladores de exceção do `fastapi.exception_handlers`:
+Se vocĂȘ quiser usar a exceção junto com os mesmos manipuladores de exceção padrĂŁo do **FastAPI**, vocĂȘ pode importar e reutilizar os manipuladores de exceção padrĂŁo de `fastapi.exception_handlers`:
{* ../../docs_src/handling_errors/tutorial006_py310.py hl[2:5,15,21] *}
-Nesse exemplo vocĂȘ apenas imprime (`print`) o erro com uma mensagem expressiva. Mesmo assim, dĂĄ para pegar a ideia. VocĂȘ pode usar a exceção e entĂŁo apenas re-usar o manipulador de exceção *default*.
+Neste exemplo, vocĂȘ estĂĄ apenas imprimindo o erro com uma mensagem muito expressiva, mas a ideia Ă© essa. VocĂȘ pode usar a exceção e entĂŁo simplesmente reutilizar os manipuladores de exceção padrĂŁo.
# Tutorial - Guia de UsuĂĄrio { #tutorial-user-guide }
-Esse tutorial mostra como usar o **FastAPI** com a maior parte de seus recursos, passo a passo.
+Este tutorial mostra como usar o **FastAPI** com a maior parte de seus recursos, passo a passo.
Cada seção constrĂłi, gradualmente, sobre as anteriores, mas sua estrutura sĂŁo tĂłpicos separados, para que vocĂȘ possa ir a qualquer um especĂfico e resolver suas necessidades especĂficas de API.
Ele tambĂ©m foi construĂdo para servir como uma referĂȘncia futura, entĂŁo vocĂȘ pode voltar e ver exatamente o que vocĂȘ precisa.
-## Rode o cĂłdigo { #run-the-code }
+## Execute o cĂłdigo { #run-the-code }
Todos os blocos de cĂłdigo podem ser copiados e utilizados diretamente (eles sĂŁo, na verdade, arquivos Python testados).
-Para rodar qualquer um dos exemplos, copie o cĂłdigo para um arquivo `main.py`, e inicie o `fastapi dev`:
+Para executar qualquer um dos exemplos, copie o cĂłdigo para um arquivo `main.py`, e inicie o `fastapi dev`:
<div class="termy">
</div>
-Ă **ALTAMENTE recomendado** que vocĂȘ escreva ou copie o cĂłdigo, edite-o e rode-o localmente.
+Ă **ALTAMENTE recomendado** que vocĂȘ escreva ou copie o cĂłdigo, edite-o e execute-o localmente.
-UsĂĄ-lo em seu editor Ă© o que realmente te mostra os benefĂcios do FastAPI, ver quĂŁo pouco cĂłdigo vocĂȘ tem que escrever, todas as conferĂȘncias de tipo, preenchimento automĂĄtico, etc.
+UsĂĄ-lo em seu editor Ă© o que realmente mostra os benefĂcios do FastAPI, vendo quĂŁo pouco cĂłdigo vocĂȘ tem que escrever, todas as verificaçÔes de tipo, preenchimento automĂĄtico, etc.
---
HĂĄ tambĂ©m um **Guia Avançado de UsuĂĄrio** que vocĂȘ pode ler apĂłs esse **Tutorial - Guia de UsuĂĄrio**.
-O **Guia Avançado de Usuårio** constrói sobre esse, usa os mesmos conceitos e te ensina algumas funcionalidades extras.
+O **Guia Avançado de Usuårio** constrói sobre esse, usa os mesmos conceitos e ensina algumas funcionalidades extras.
Mas vocĂȘ deveria ler primeiro o **Tutorial - Guia de UsuĂĄrio** (que vocĂȘ estĂĄ lendo agora).
| `title` | `str` | O tĂtulo da API. |
| `summary` | `str` | Um breve resumo da API. <small>DisponĂvel desde OpenAPI 3.1.0, FastAPI 0.99.0.</small> |
| `description` | `str` | Uma breve descrição da API. Pode usar Markdown. |
-| `version` | `string` | A versão da API. Esta é a versão da sua aplicação, não do OpenAPI. Por exemplo, `2.5.0`. |
+| `version` | `str` | A versão da API. Esta é a versão da sua aplicação, não do OpenAPI. Por exemplo, `2.5.0`. |
| `terms_of_service` | `str` | Uma URL para os Termos de Serviço da API. Se fornecido, deve ser uma URL. |
| `contact` | `dict` | As informaçÔes de contato da API exposta. Pode conter vårios campos. <details><summary>Campos de <code>contact</code></summary><table><thead><tr><th>Parùmetro</th><th>Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td>O nome identificador da pessoa/organização de contato.</td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>A URL que aponta para as informaçÔes de contato. DEVE estar no formato de uma URL.</td></tr><tr><td><code>email</code></td><td><code>str</code></td><td>O endereço de e-mail da pessoa/organização de contato. DEVE estar no formato de um endereço de e-mail.</td></tr></tbody></table></details> |
| `license_info` | `dict` | As informaçÔes de licença para a API exposta. Ela pode conter vĂĄrios campos. <details><summary>Campos de <code>license_info</code></summary><table><thead><tr><th>ParĂąmetro</th><th>Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td><strong>OBRIGATĂRIO</strong> (se um <code>license_info</code> for definido). O nome da licença usada para a API.</td></tr><tr><td><code>identifier</code></td><td><code>str</code></td><td>Uma expressĂŁo de licença [SPDX](https://spdx.org/licenses/) para a API. O campo <code>identifier</code> Ă© mutuamente exclusivo do campo <code>url</code>. <small>DisponĂvel desde OpenAPI 3.1.0, FastAPI 0.99.0.</small></td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>Uma URL para a licença usada para a API. DEVE estar no formato de uma URL.</td></tr></tbody></table></details> |
///
-### Cheque os documentos { #check-the-docs }
+### Verifique a documentação { #check-the-docs }
Agora, se vocĂȘ verificar a documentação, ela exibirĂĄ todos os metadados adicionais:
### Tags com Enums { #tags-with-enums }
-Se vocĂȘ tem uma grande aplicação, vocĂȘ pode acabar acumulando **vĂĄrias tags**, e vocĂȘ gostaria de ter certeza de que vocĂȘ sempre usa a ** mesma tag** para *operaçÔes de rota* relacionadas.
+Se vocĂȘ tem uma grande aplicação, vocĂȘ pode acabar acumulando **vĂĄrias tags**, e vocĂȘ gostaria de ter certeza de que vocĂȘ sempre usa a **mesma tag** para *operaçÔes de rota* relacionadas.
Nestes casos, pode fazer sentido armazenar as tags em um `Enum`.
## Validação adicional { #additional-validation }
-Vamos impor que, embora `q` seja opcional, sempre que for fornecido, seu comprimento nĂŁo exceda 50 caracteres.
+Vamos impor que, embora `q` seja opcional, sempre que for fornecido, **seu comprimento nĂŁo exceda 50 caracteres**.
### Importe `Query` e `Annotated` { #import-query-and-annotated }
Perceba que o valor padrĂŁo continua sendo `None`, entĂŁo o parĂąmetro ainda Ă© opcional.
-Mas agora, com `Query(max_length=50)` dentro de `Annotated`, estamos dizendo ao FastAPI que queremos validação adicional para este valor, queremos que tenha no mĂĄximo 50 caracteres. đ
+Mas agora, com `Query(max_length=50)` dentro de `Annotated`, estamos dizendo ao FastAPI que queremos **validação adicional** para este valor, queremos que tenha no mĂĄximo 50 caracteres. đ
/// tip | Dica
-Aqui estamos usando `Query()` porque este é um parùmetro de consulta. Mais adiante veremos outros como `Path()`, `Body()`, `Header()` e `Cookie()`, que também aceitam os mesmos argumentos que `Query()`.
+Aqui estamos usando `Query()` porque este é um **parùmetro de consulta**. Mais adiante veremos outros como `Path()`, `Body()`, `Header()` e `Cookie()`, que também aceitam os mesmos argumentos que `Query()`.
///
Agora o FastAPI vai:
-* Validar os dados garantindo que o comprimento mĂĄximo seja de 50 caracteres
-* Mostrar um erro claro para o cliente quando os dados nĂŁo forem vĂĄlidos
-* Documentar o parùmetro na operação de rota do esquema OpenAPI (então ele aparecerå na UI de docs automåtica)
+* **Validar** os dados garantindo que o comprimento mĂĄximo seja de 50 caracteres
+* Mostrar um **erro claro** para o cliente quando os dados nĂŁo forem vĂĄlidos
+* **Documentar** o parùmetro na *operação de rota* do esquema OpenAPI (então ele aparecerå na **UI de documentação automåtica**)
## Alternativa (antiga): `Query` como valor padrĂŁo { #alternative-old-query-as-the-default-value }
q: str | None = Query(default=None, max_length=50)
```
-Isso validarå os dados, mostrarå um erro claro quando os dados não forem vålidos e documentarå o parùmetro na operação de rota do esquema OpenAPI.
+Isso validarå os dados, mostrarå um erro claro quando os dados não forem vålidos e documentarå o parùmetro na *operação de rota* do esquema OpenAPI.
### `Query` como valor padrĂŁo ou em `Annotated` { #query-as-the-default-value-or-in-annotated }
### Vantagens de `Annotated` { #advantages-of-annotated }
-Usar `Annotated` Ă© recomendado em vez do valor padrĂŁo nos parĂąmetros da função, Ă© melhor por vĂĄrios motivos. đ€
+**Usar `Annotated` Ă© recomendado** em vez do valor padrĂŁo nos parĂąmetros da função, Ă© **melhor** por vĂĄrios motivos. đ€
-O valor padrĂŁo do parĂąmetro da função Ă© o valor padrĂŁo real, isso Ă© mais intuitivo com Python em geral. đ
+O valor **padrĂŁo** do **parĂąmetro da função** Ă© o valor **padrĂŁo real**, isso Ă© mais intuitivo com Python em geral. đ
-VocĂȘ poderia chamar essa mesma função em outros lugares sem FastAPI, e ela funcionaria como esperado. Se houver um parĂąmetro obrigatĂłrio (sem valor padrĂŁo), seu editor vai avisar com um erro, e o Python tambĂ©m reclamarĂĄ se vocĂȘ executĂĄ-la sem passar o parĂąmetro obrigatĂłrio.
+VocĂȘ poderia **chamar** essa mesma função em **outros lugares** sem FastAPI, e ela **funcionaria como esperado**. Se houver um parĂąmetro **obrigatĂłrio** (sem valor padrĂŁo), seu **editor** vai avisar com um erro, e o **Python** tambĂ©m reclamarĂĄ se vocĂȘ executĂĄ-la sem passar o parĂąmetro obrigatĂłrio.
-Quando vocĂȘ nĂŁo usa `Annotated` e em vez disso usa o estilo de valor padrĂŁo (antigo), se vocĂȘ chamar essa função sem FastAPI em outros lugares, terĂĄ que lembrar de passar os argumentos para a função para que funcione corretamente, caso contrĂĄrio os valores serĂŁo diferentes do esperado (por exemplo, `QueryInfo` ou algo parecido em vez de `str`). E seu editor nĂŁo vai avisar, e o Python tambĂ©m nĂŁo vai reclamar ao executar a função, apenas quando as operaçÔes internas falharem.
+Quando vocĂȘ nĂŁo usa `Annotated` e em vez disso usa o **estilo de valor padrĂŁo (antigo)**, se vocĂȘ chamar essa função sem FastAPI em **outros lugares**, terĂĄ que **lembrar** de passar os argumentos para a função para que funcione corretamente, caso contrĂĄrio os valores serĂŁo diferentes do esperado (por exemplo, `QueryInfo` ou algo parecido em vez de `str`). E seu editor nĂŁo vai avisar, e o Python tambĂ©m nĂŁo vai reclamar ao executar a função, apenas quando as operaçÔes internas falharem.
Como `Annotated` pode ter mais de uma anotação de metadados, vocĂȘ agora pode atĂ© usar a mesma função com outras ferramentas, como o [Typer](https://typer.tiangolo.com/). đ
## Adicione expressÔes regulares { #add-regular-expressions }
-VocĂȘ pode definir um `pattern` de <dfn title="Uma expressĂŁo regular (regex ou regexp) Ă© uma sequĂȘncia de caracteres que define um padrĂŁo de busca para strings.">expressĂŁo regular</dfn> que o parĂąmetro deve corresponder:
+VocĂȘ pode definir um `pattern` de <dfn title="Uma expressĂŁo regular, regex ou regexp Ă© uma sequĂȘncia de caracteres que define um padrĂŁo de busca para strings.">expressĂŁo regular</dfn> que o parĂąmetro deve corresponder:
{* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *}
* `fixedquery`: tem exatamente o valor `fixedquery`.
* `$`: termina ali, nĂŁo tem mais caracteres depois de `fixedquery`.
-Se vocĂȘ se sentir perdido com essas ideias de "expressĂŁo regular", nĂŁo se preocupe. Esse Ă© um assunto difĂcil para muitas pessoas. VocĂȘ ainda pode fazer muitas coisas sem precisar de expressĂ”es regulares por enquanto.
+Se vocĂȘ se sentir perdido com essas ideias de **"expressĂŁo regular"**, nĂŁo se preocupe. Esse Ă© um assunto difĂcil para muitas pessoas. VocĂȘ ainda pode fazer muitas coisas sem precisar de expressĂ”es regulares por enquanto.
-Agora vocĂȘ sabe que, sempre que precisar delas, pode usĂĄ-las no FastAPI.
+Agora vocĂȘ sabe que, sempre que precisar delas, pode usĂĄ-las no **FastAPI**.
## Valores padrĂŁo { #default-values }
http://localhost:8000/items/?q=foo&q=bar
```
-vocĂȘ receberia os mĂșltiplos valores dos parĂąmetros de consulta `q` (`foo` e `bar`) em uma `list` Python dentro da sua função de operação de rota, no parĂąmetro da função `q`.
+vocĂȘ receberia os mĂșltiplos valores dos *parĂąmetros de consulta* `q` (`foo` e `bar`) em uma `list` Python dentro da sua *função de operação de rota*, no *parĂąmetro da função* `q`.
Assim, a resposta para essa URL seria:
## Excluir parĂąmetros do OpenAPI { #exclude-parameters-from-openapi }
-Para excluir um parùmetro de consulta do OpenAPI gerado (e portanto, dos sistemas de documentação automåticos), defina o parùmetro `include_in_schema` de `Query` como `False`:
+Para excluir um parùmetro de consulta do esquema OpenAPI gerado (e portanto, dos sistemas de documentação automåticos), defina o parùmetro `include_in_schema` de `Query` como `False`:
{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
## Validação personalizada { #custom-validation }
-Podem existir casos em que vocĂȘ precise fazer alguma validação personalizada que nĂŁo pode ser feita com os parĂąmetros mostrados acima.
+Podem existir casos em que vocĂȘ precise fazer alguma **validação personalizada** que nĂŁo pode ser feita com os parĂąmetros mostrados acima.
-Nesses casos, vocĂȘ pode usar uma função validadora personalizada que Ă© aplicada apĂłs a validação normal (por exemplo, depois de validar que o valor Ă© uma `str`).
+Nesses casos, vocĂȘ pode usar uma **função validadora personalizada** que Ă© aplicada apĂłs a validação normal (por exemplo, depois de validar que o valor Ă© uma `str`).
VocĂȘ pode fazer isso usando o [`AfterValidator` do Pydantic](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) dentro de `Annotated`.
/// tip | Dica
-Se vocĂȘ precisar fazer qualquer tipo de validação que exija comunicação com algum componente externo, como um banco de dados ou outra API, vocĂȘ deveria usar DependĂȘncias do FastAPI em vez disso; vocĂȘ aprenderĂĄ sobre elas mais adiante.
+Se vocĂȘ precisar fazer qualquer tipo de validação que exija comunicação com algum **componente externo**, como um banco de dados ou outra API, vocĂȘ deveria usar **DependĂȘncias do FastAPI** em vez disso; vocĂȘ aprenderĂĄ sobre elas mais adiante.
-Esses validadores personalizados são para coisas que podem ser verificadas apenas com os mesmos dados fornecidos na requisição.
+Esses validadores personalizados são para coisas que podem ser verificadas **apenas** com os **mesmos dados** fornecidos na requisição.
///
### Entenda esse cĂłdigo { #understand-that-code }
-O ponto importante Ă© apenas usar `AfterValidator` com uma função dentro de `Annotated`. Sinta-se Ă vontade para pular esta parte. đ€ž
+O ponto importante Ă© apenas usar **`AfterValidator` com uma função dentro de `Annotated`**. Sinta-se Ă vontade para pular esta parte. đ€ž
---
Convertemos esse objeto iterĂĄvel em uma `list` adequada com `list(data.items())`.
-Em seguida, com `random.choice()` podemos obter um valor aleatĂłrio da lista, entĂŁo obtemos uma tupla com `(id, name)`. SerĂĄ algo como `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`.
+Em seguida, com `random.choice()` podemos obter um **valor aleatĂłrio** da lista, entĂŁo obtemos uma tupla com `(id, name)`. SerĂĄ algo como `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`.
-Depois atribuĂmos esses dois valores da tupla Ă s variĂĄveis `id` e `name`.
+Depois **atribuĂmos esses dois valores** da tupla Ă s variĂĄveis `id` e `name`.
Assim, se o usuĂĄrio nĂŁo fornecer um ID de item, ele ainda receberĂĄ uma sugestĂŁo aleatĂłria.
-...fazemos tudo isso em uma Ășnica linha simples. đ€Ż VocĂȘ nĂŁo ama Python? đ
+...fazemos tudo isso em uma **Ășnica linha simples**. đ€Ż VocĂȘ nĂŁo ama Python? đ
{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[22:30] hl[29] *}
Os valores dos parùmetros na sua função serão:
-* `skip=20`: Por que vocĂȘ definiu isso na URL
-* `limit=10`: Por que esse era o valor padrĂŁo
+* `skip=20`: porque vocĂȘ definiu isso na URL
+* `limit=10`: porque esse era o valor padrĂŁo
## ParĂąmetros opcionais { #optional-parameters }
ou qualquer outra variação (tudo em maiĂșscula, primeira letra em maiĂșscula, etc), a sua função vai ver o parĂąmetro `short` com um valor `bool` de `True`. Caso contrĂĄrio `False`.
+
## MĂșltiplos parĂąmetros de rota e consulta { #multiple-path-and-query-parameters }
VocĂȘ pode declarar mĂșltiplos parĂąmetros de rota e parĂąmetros de consulta ao mesmo tempo, o **FastAPI** vai saber o quĂȘ Ă© o quĂȘ.
{* ../../docs_src/query_params/tutorial005_py310.py hl[6:7] *}
-Aqui o parĂąmetro da consulta `needy` Ă© um valor obrigatĂłrio, do tipo `str`.
+Aqui o parĂąmetro da consulta `needy` Ă© um parĂąmetro de consulta obrigatĂłrio, do tipo `str`.
-Se vocĂȘ abrir no seu navegador a URL:
+Se vocĂȘ abrir no seu navegador uma URL como:
```
http://127.0.0.1:8000/items/foo-item
Os arquivos serĂŁo enviados como "dados de formulĂĄrio".
-Se vocĂȘ declarar o tipo do parĂąmetro da função da sua *operação de rota* como `bytes`, o **FastAPI** lerĂĄ o arquivo para vocĂȘ e vocĂȘ receberĂĄ o conteĂșdo como `bytes`.
+Se vocĂȘ declarar o tipo do parĂąmetro da sua *função de operação de rota* como `bytes`, o **FastAPI** lerĂĄ o arquivo para vocĂȘ e vocĂȘ receberĂĄ o conteĂșdo como `bytes`.
Mantenha em mente que isso significa que todo o conteĂșdo serĂĄ armazenado na memĂłria. Isso funcionarĂĄ bem para arquivos pequenos.
* Um arquivo armazenado na memória até um limite måximo de tamanho, e após passar esse limite, ele serå armazenado no disco.
* Isso significa que funcionarĂĄ bem para arquivos grandes como imagens, vĂdeos, binĂĄrios grandes, etc., sem consumir toda a memĂłria.
* VocĂȘ pode receber metadados do arquivo enviado.
-* Ele tem uma [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) interface `assĂncrona`.
-* Ele expĂ”e um objeto python [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile) que vocĂȘ pode passar diretamente para outras bibliotecas que esperam um objeto semelhante a um arquivo.
+* Ele tem uma interface [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) `async`.
+* Ele expĂ”e um objeto Python [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile) real que vocĂȘ pode passar diretamente para outras bibliotecas que esperam um objeto semelhante a um arquivo.
### `UploadFile` { #uploadfile }
* `filename`: Uma `str` com o nome do arquivo original que foi enviado (por exemplo, `myimage.jpg`).
* `content_type`: Uma `str` com o tipo de conteĂșdo (MIME type / media type) (por exemplo, `image/jpeg`).
-* `file`: Um [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile) (um [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) objeto). Este Ă© o objeto de arquivo Python que vocĂȘ pode passar diretamente para outras funçÔes ou bibliotecas que esperam um objeto semelhante a um arquivo.
+* `file`: Um [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile) (um objeto [file-like](https://docs.python.org/3/glossary.html#term-file-like-object)). Este Ă© o objeto de arquivo Python que vocĂȘ pode passar diretamente para outras funçÔes ou bibliotecas que esperam um objeto semelhante a um arquivo.
-`UploadFile` tem os seguintes mĂ©todos `assĂncronos`. Todos eles chamam os mĂ©todos de arquivo correspondentes por baixo dos panos (usando o `SpooledTemporaryFile` interno).
+`UploadFile` tem os seguintes métodos `async`. Todos eles chamam os métodos de arquivo correspondentes por baixo dos panos (usando o `SpooledTemporaryFile` interno).
* `write(data)`: Escreve `data` (`str` ou `bytes`) no arquivo.
* `read(size)`: LĂȘ `size` (`int`) bytes/caracteres do arquivo.
* Isso Ă© especialmente Ăștil se vocĂȘ executar `await myfile.read()` uma vez e precisar ler o conteĂșdo novamente.
* `close()`: Fecha o arquivo.
-Como todos esses mĂ©todos sĂŁo mĂ©todos `assĂncronos`, vocĂȘ precisa "aguardar" por eles.
+Como todos esses mĂ©todos sĂŁo mĂ©todos `async`, vocĂȘ precisa "aguardar" por eles.
-Por exemplo, dentro de uma função de *operação de rota* `assĂncrona`, vocĂȘ pode obter o conteĂșdo com:
+Por exemplo, dentro de uma *função de operação de rota* `async`, vocĂȘ pode obter o conteĂșdo com:
```Python
contents = await myfile.read()
```
-Se vocĂȘ estiver dentro de uma função de *operação de rota* normal `def`, vocĂȘ pode acessar o `UploadFile.file` diretamente, por exemplo:
+Se vocĂȘ estiver dentro de uma *função de operação de rota* normal `def`, vocĂȘ pode acessar o `UploadFile.file` diretamente, por exemplo:
```Python
contents = myfile.file.read()
///
-## O que Ă© "Form Data" { #what-is-form-data }
+## O que sĂŁo "Dados de FormulĂĄrio" { #what-is-form-data }
O jeito que os formulårios HTML (`<form></form>`) enviam os dados para o servidor normalmente usa uma codificação "especial" para esses dados, a qual é diferente do JSON.
Dados de formulĂĄrios normalmente sĂŁo codificados usando o "media type" `application/x-www-form-urlencoded` quando nĂŁo incluem arquivos.
-Mas quando o formulĂĄrio inclui arquivos, ele Ă© codificado como `multipart/form-data`. Se vocĂȘ usar `File`, o **FastAPI** saberĂĄ que tem que pegar os arquivos da parte correta do corpo da requisição.
+Mas quando o formulĂĄrio inclui arquivos, ele Ă© codificado como `multipart/form-data`. Se vocĂȘ usar `File`, o **FastAPI** saberĂĄ que tem que pegar os arquivos da parte correta do corpo.
-Se vocĂȘ quiser ler mais sobre essas codificaçÔes e campos de formulĂĄrio, vĂĄ para a [<abbr title="Mozilla Developer Network - Rede de Desenvolvedores da Mozilla">MDN</abbr> web docs para `POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST).
+Se vocĂȘ quiser ler mais sobre essas codificaçÔes e campos de formulĂĄrio, vĂĄ para a [documentação web da <abbr title="Mozilla Developer Network - Rede de Desenvolvedores da Mozilla">MDN</abbr> para `POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST).
///
Mas quando o formulĂĄrio inclui arquivos, ele Ă© codificado como `multipart/form-data`. VocĂȘ lerĂĄ sobre como lidar com arquivos no prĂłximo capĂtulo.
-Se vocĂȘ quiser ler mais sobre essas codificaçÔes e campos de formulĂĄrio, vĂĄ para o [<abbr title="Mozilla Developer Network - Rede de Desenvolvedores da Mozilla">MDN</abbr> web docs para `POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST).
+Se vocĂȘ quiser ler mais sobre essas codificaçÔes e campos de formulĂĄrio, vĂĄ para a [documentação web da <abbr title="Mozilla Developer Network - Rede de Desenvolvedores da Mozilla">MDN</abbr> para `POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST).
///
/// note | Nota
-Observe que `status_code` é um parùmetro do método "decorador" (`get`, `post`, etc). Não da sua função de *operação de rota*, como todos os parùmetros e corpo.
+Observe que `status_code` é um parùmetro do método "decorador" (`get`, `post`, etc). Não da sua *função de operação de rota*, como todos os parùmetros e corpo.
///
Alguns códigos de resposta (consulte a próxima seção) indicam que a resposta não possui um corpo.
-O FastAPI sabe disso e produzirĂĄ documentos OpenAPI informando que nĂŁo hĂĄ corpo de resposta.
+O FastAPI sabe disso e produzirå documentação OpenAPI informando que não hå corpo de resposta.
///
{* ../../docs_src/response_status_code/tutorial002_py310.py hl[1,6] *}
-Eles sĂŁo apenas uma conveniĂȘncia, eles possuem o mesmo nĂșmero, mas dessa forma vocĂȘ pode usar o preenchimento automĂĄtico do editor para encontrĂĄ-los:
+Eles sĂŁo apenas uma conveniĂȘncia, eles possuem o mesmo nĂșmero, mas dessa forma vocĂȘ pode usar o autocompletar do editor para encontrĂĄ-los:
<img src="/img/tutorial/response-status-code/image02.png">
# Declare dados de exemplo da requisição { #declare-request-example-data }
+
VocĂȘ pode declarar exemplos dos dados que sua aplicação pode receber.
Aqui estĂŁo vĂĄrias maneiras de fazer isso.
/// tip | BotĂŁo Autorizar!
-VocĂȘ jĂĄ tem um novo botĂŁo 'Authorize'.
+VocĂȘ jĂĄ tem um novo e brilhante botĂŁo "Authorize".
-E sua operação de rota tem um pequeno cadeado no canto superior direito em que vocĂȘ pode clicar.
+E sua *operação de rota* tem um pequeno cadeado no canto superior direito em que vocĂȘ pode clicar.
///
Claro que este nĂŁo Ă© o frontend para os usuĂĄrios finais, mas Ă© uma Ăłtima ferramenta automĂĄtica para documentar interativamente toda a sua API.
-Pode ser usada pelo time de frontend (que pode ser vocĂȘ mesmo).
+Pode ser usada pela equipe de frontend (que pode ser vocĂȘ mesmo).
Pode ser usada por aplicaçÔes e sistemas de terceiros.
* EntĂŁo, o usuĂĄrio terĂĄ que fazer login novamente em algum momento.
* E se o token for roubado, o risco Ă© menor. NĂŁo Ă© como uma chave permanente que funcionarĂĄ para sempre (na maioria dos casos).
* O frontend armazena esse token temporariamente em algum lugar.
-* O usuårio clica no frontend para ir para outra seção do aplicativo web.
+* O usuårio clica no frontend para ir para outra seção da aplicação web do frontend.
* O frontend precisa buscar mais dados da API.
* Mas precisa de autenticação para aquele endpoint especĂfico.
* EntĂŁo, para autenticar com nossa API, ele envia um header `Authorization` com o valor `Bearer ` mais o token.
///
-Esse parùmetro não cria aquele endpoint/operação de rota, mas declara que a URL `/token` serå aquela que o client deve usar para obter o token. Essa informação é usada no OpenAPI e depois nos sistemas de documentação interativa da API.
+Esse parùmetro não cria aquele endpoint / *operação de rota*, mas declara que a URL `/token` serå aquela que o client deve usar para obter o token. Essa informação é usada no OpenAPI e depois nos sistemas de documentação interativa da API.
Em breve também criaremos a operação de rota real.
Da mesma forma que usamos o Pydantic para declarar corpos, podemos usĂĄ-lo em qualquer outro lugar:
-{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:16] *}
## Criar uma dependĂȘncia `get_current_user` { #create-a-get-current-user-dependency }
# OAuth2 com Senha (e hashing), Bearer com tokens JWT { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens }
-Agora que temos todo o fluxo de segurança, vamos tornar a aplicação realmente segura, usando tokens <abbr title="JSON Web Tokens">JWT</abbr> e hashing de senhas seguras.
+Agora que temos todo o fluxo de segurança, vamos tornar a aplicação realmente segura, usando tokens <abbr title="JSON Web Tokens">JWT</abbr> e hashing seguro de senhas.
Este cĂłdigo Ă© algo que vocĂȘ pode realmente usar na sua aplicação, salvar os hashes das senhas no seu banco de dados, etc.
/// note | Nota
-Se vocĂȘ pretende utilizar algoritmos de assinatura digital como o RSA ou o ECDSA, vocĂȘ deve instalar a dependĂȘncia da biblioteca de criptografia `pyjwt[crypto]`.
+Se vocĂȘ pretende utilizar algoritmos de assinatura digital como o RSA ou o ECDSA, vocĂȘ deveria instalar a dependĂȘncia da biblioteca de criptografia `pyjwt[crypto]`.
VocĂȘ pode ler mais sobre isso na [documentação de instalação do PyJWT](https://pyjwt.readthedocs.io/en/latest/installation.html).
Com o `pwdlib`, vocĂȘ poderia atĂ© configurĂĄ-lo para ser capaz de ler senhas criadas pelo **Django**, um plug-in de segurança do **Flask** ou muitos outros.
-Assim, vocĂȘ poderia, por exemplo, compartilhar os mesmos dados de um aplicativo Django em um banco de dados com um aplicativo FastAPI. Ou migrar gradualmente uma aplicação Django usando o mesmo banco de dados.
+Assim, vocĂȘ poderia, por exemplo, compartilhar os mesmos dados de uma aplicação Django em um banco de dados com uma aplicação FastAPI. Ou migrar gradualmente uma aplicação Django usando o mesmo banco de dados.
E seus usuårios poderiam fazer login tanto pela sua aplicação Django quanto pela sua aplicação **FastAPI**, ao mesmo tempo.
Em quase qualquer framework, lidar com a segurança se torna rapidamente um assunto bastante complexo.
-Muitos pacotes que simplificam bastante isso precisam fazer muitas concessĂ”es com o modelo de dados, o banco de dados e os recursos disponĂveis. E alguns desses pacotes que simplificam demais na verdade tĂȘm falhas de segurança subjacentes.
+Muitos pacotes que simplificam bastante isso precisam fazer muitas concessĂ”es com o modelo de dados, o banco de dados e as funcionalidades disponĂveis. E alguns desses pacotes que simplificam demais na verdade tĂȘm falhas de segurança subjacentes.
---
Vamos usar os utilitårios de segurança da **FastAPI** para obter o `username` e a `password`.
-OAuth2 especifica que ao usar o "password flow" (fluxo de senha), que estamos usando, o cliente/usuĂĄrio deve enviar os campos `username` e `password` como dados do formulĂĄrio.
+OAuth2 especifica que, ao usar o "fluxo de senha" (que estamos usando), o cliente/usuĂĄrio deve enviar os campos `username` e `password` como dados do formulĂĄrio.
E a especificação diz que os campos devem ser nomeados assim. Portanto, `user-name` ou `email` não funcionariam.
Normalmente sĂŁo usados para declarar permissĂ”es de segurança especĂficas, por exemplo:
* `users:read` ou `users:write` sĂŁo exemplos comuns.
-* `instagram_basic` Ă© usado pelo Facebook e Instagram.
+* `instagram_basic` Ă© usado pelo Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` Ă© usado pelo Google.
/// note | Nota
`OAuth2PasswordBearer` faz com que **FastAPI** saiba que é um esquema de segurança. Portanto, é adicionado dessa forma ao OpenAPI.
-Mas `OAuth2PasswordRequestForm` Ă© apenas uma dependĂȘncia de classe que vocĂȘ mesmo poderia ter escrito ou poderia ter declarado os parĂąmetros do `Form` (formulĂĄrio) diretamente.
+Mas `OAuth2PasswordRequestForm` Ă© apenas uma dependĂȘncia de classe que vocĂȘ mesmo poderia ter escrito ou poderia ter declarado os parĂąmetros de `Form` diretamente.
Mas como Ă© um caso de uso comum, ele Ă© fornecido diretamente pelo **FastAPI**, apenas para facilitar.
Vamos colocar esses dados primeiro no modelo `UserInDB` do Pydantic.
-VocĂȘ nunca deve salvar senhas em texto simples, portanto, usaremos o sistema de hashing de senhas (falsas).
+VocĂȘ nunca deveria salvar senhas em texto simples, portanto, usaremos o sistema (falso) de hashing de senhas.
Se as senhas nĂŁo corresponderem, retornaremos o mesmo erro.
Mas vocĂȘ nĂŁo pode converter a sequĂȘncia aleatĂłria de caracteres de volta para a senha.
-##### Porque usar hashing de senha { #why-use-password-hashing }
+##### Por que usar hashing de senha { #why-use-password-hashing }
Se o seu banco de dados for roubado, o ladrĂŁo nĂŁo terĂĄ as senhas em texto simples dos seus usuĂĄrios, apenas os hashes.
/// note | Nota
-Para uma explicação mais completa de `**user_dict`, verifique [a documentação para **Extra Models**](../extra-models.md#about-user-in-dict).
+Para uma explicação mais completa de `**user_dict`, verifique [a documentação para **Extra Models**](../extra-models.md#about-user-in-model-dump).
///
Aqui veremos um exemplo usando [SQLModel](https://sqlmodel.tiangolo.com/).
-**SQLModel** Ă© construĂdo sobre [SQLAlchemy](https://www.sqlalchemy.org/) e Pydantic. Ele foi criado pelo mesmo autor do **FastAPI** para ser o par perfeito para aplicaçÔes **FastAPI** que precisam usar **bancos de dados SQL**.
+**SQLModel** Ă© construĂdo sobre [SQLAlchemy](https://www.sqlalchemy.org/) e Pydantic. Ele foi criado pelo mesmo autor do **FastAPI** para ser o par perfeito para aplicaçÔes FastAPI que precisam usar **bancos de dados SQL**.
/// tip | Dica
Este Ă© um tutorial muito simples e curto, se vocĂȘ quiser aprender sobre bancos de dados em geral, sobre SQL ou recursos mais avançados, acesse a [documentação do SQLModel](https://sqlmodel.tiangolo.com/).
-## Instalar o `SQLModel` { #install-sqlmodel }
+## Instale o `SQLModel` { #install-sqlmodel }
Primeiro, certifique-se de criar seu [ambiente virtual](../virtual-environments.md), ativĂĄ-lo e, em seguida, instalar o `sqlmodel`:
</div>
-## Crear o App com um Ănico Modelo { #create-the-app-with-a-single-model }
+## Crie o App com um Ănico Modelo { #create-the-app-with-a-single-model }
Vamos criar a primeira versĂŁo mais simples do app com um Ășnico modelo **SQLModel**.
Depois, vamos melhorĂĄ-lo aumentando a segurança e versatilidade com **mĂșltiplos modelos** abaixo. đ€
-### Criar Modelos { #create-models }
+### Crie Modelos { #create-models }
Importe o `SQLModel` e crie um modelo de banco de dados:
O SQLModel saberĂĄ que algo declarado como `str` serĂĄ uma coluna SQL do tipo `TEXT` (ou `VARCHAR`, dependendo do banco de dados).
-### Criar um Engine { #create-an-engine }
+### Crie um Engine { #create-an-engine }
+
Um `engine` SQLModel (por baixo dos panos, ele é na verdade um `engine` do SQLAlchemy) é o que **mantém as conexÔes** com o banco de dados.
VocĂȘ teria **um Ășnico objeto `engine`** para todo o seu cĂłdigo se conectar ao mesmo banco de dados.
NĂŁo se preocupe, com a forma como o cĂłdigo estĂĄ estruturado, garantiremos que usamos **uma Ășnica *sessĂŁo* SQLModel por requisição** mais tarde, isso Ă© realmente o que o `check_same_thread` estĂĄ tentando conseguir.
-### Criar as Tabelas { #create-the-tables }
+### Crie as Tabelas { #create-the-tables }
Em seguida, adicionamos uma função que usa `SQLModel.metadata.create_all(engine)` para **criar as tabelas** para todos os *modelos de tabela*.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[21:22] hl[21:22] *}
-### Criar uma DependĂȘncia de SessĂŁo { #create-a-session-dependency }
+### Crie uma DependĂȘncia de SessĂŁo { #create-a-session-dependency }
Uma **`Session`** é o que armazena os **objetos na memória** e acompanha as alteraçÔes necessårias nos dados, para então **usar o `engine`** para se comunicar com o banco de dados.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[25:30] hl[25:27,30] *}
-### Criar Tabelas de Banco de Dados na Inicialização { #create-database-tables-on-startup }
+### Crie Tabelas de Banco de Dados na Inicialização { #create-database-tables-on-startup }
Vamos criar as tabelas do banco de dados quando o aplicativo for iniciado.
///
-### Criar um Hero { #create-a-hero }
+### Crie um Hero { #create-a-hero }
Como cada modelo SQLModel tambĂ©m Ă© um modelo Pydantic, vocĂȘ pode usĂĄ-lo nas mesmas **anotaçÔes de tipo** que usaria para modelos Pydantic.
Aqui, usamos a dependĂȘncia `SessionDep` (uma `Session`) para adicionar o novo `Hero` Ă instĂąncia `Session`, fazer commit das alteraçÔes no banco de dados, atualizar os dados no `hero` e entĂŁo retornĂĄ-lo.
-### Ler Heroes { #read-heroes }
+### Leia Heroes { #read-heroes }
Podemos **ler** `Hero`s do banco de dados usando um `select()`. Podemos incluir um `limit` e `offset` para paginar os resultados.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[48:55] hl[51:52,54] *}
-### Ler um Ănico Hero { #read-one-hero }
+### Leia um Ănico Hero { #read-one-hero }
Podemos **ler** um Ășnico `Hero`.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[58:63] hl[60] *}
-### Deletar um Hero { #delete-a-hero }
+### Delete um Hero { #delete-a-hero }
Também podemos **deletar** um `Hero`.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[66:73] hl[71] *}
-### Executar o App { #run-the-app }
+### Execute o App { #run-the-app }
VocĂȘ pode executar o app:
<img src="/img/tutorial/sql-databases/image01.png">
</div>
-## Atualizar o App com MĂșltiplos Modelos { #update-the-app-with-multiple-models }
+## Atualize o App com MĂșltiplos Modelos { #update-the-app-with-multiple-models }
Agora vamos **refatorar** este app um pouco para aumentar a **segurança** e **versatilidade**.
-Se vocĂȘ verificar o app anterior, na interface vocĂȘ pode ser que, atĂ© agora, ele permite que o cliente decida o `id` do `Hero` a ser criado. đ±
+Se vocĂȘ verificar o app anterior, na interface vocĂȘ pode ver que, atĂ© agora, ele permite que o cliente decida o `id` do `Hero` a ser criado. đ±
-NĂŁo deverĂamos deixar isso acontecer, eles poderiam sobrescrever um `id` que jĂĄ atribuimos na base de dados. Decidir o `id` deve ser feito pelo **backend** ou pelo **banco de dados**, **nĂŁo pelo cliente**.
+NĂŁo deverĂamos deixar isso acontecer, eles poderiam sobrescrever um `id` que jĂĄ atribuĂmos no banco de dados. Decidir o `id` deve ser feito pelo **backend** ou pelo **banco de dados**, **nĂŁo pelo cliente**.
AlĂ©m disso, criamos um `secret_name` para o hero, mas atĂ© agora estamos retornando ele em todos os lugares, isso nĂŁo Ă© muito **secreto**... đ
Vamos corrigir essas coisas adicionando alguns **modelos extras**. Aqui Ă© onde o SQLModel vai brilhar. âš
-### Criar MĂșltiplos Modelos { #create-multiple-models }
+### Crie MĂșltiplos Modelos { #create-multiple-models }
No **SQLModel**, qualquer classe de modelo que tenha `table=True` Ă© um **modelo de tabela**.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:28] hl[25:28] *}
-### Criar com `HeroCreate` e retornar um `HeroPublic` { #create-with-herocreate-and-return-a-heropublic }
+### Crie com `HeroCreate` e retorne um `HeroPublic` { #create-with-herocreate-and-return-a-heropublic }
Agora que temos **mĂșltiplos modelos**, podemos atualizar as partes do app que os utilizam.
///
-### Ler Heroes com `HeroPublic` { #read-heroes-with-heropublic }
+### Leia Heroes com `HeroPublic` { #read-heroes-with-heropublic }
Podemos fazer o mesmo que antes para **ler** `Hero`s, novamente, usamos `response_model=list[HeroPublic]` para garantir que os dados sejam validados e serializados corretamente.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[65:72] hl[65] *}
-### Ler Um Hero com `HeroPublic` { #read-one-hero-with-heropublic }
+### Leia Um Hero com `HeroPublic` { #read-one-hero-with-heropublic }
Podemos **ler** um Ășnico herĂłi:
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[75:80] hl[77] *}
-### Atualizar um Hero com `HeroUpdate` { #update-a-hero-with-heroupdate }
+### Atualize um Hero com `HeroUpdate` { #update-a-hero-with-heroupdate }
Podemos **atualizar um hero**. Para isso, usamos uma operação HTTP `PATCH`.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[83:93] hl[83:84,88:89] *}
-### Deletar um Hero Novamente { #delete-a-hero-again }
+### Delete um Hero Novamente { #delete-a-hero-again }
**Deletar** um hero permanece praticamente o mesmo.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[96:103] hl[101] *}
-### Executar o App Novamente { #run-the-app-again }
+### Execute o App Novamente { #run-the-app-again }
VocĂȘ pode executar o app novamente:
VocĂȘ pode servir arquivos estĂĄticos automaticamente a partir de um diretĂłrio usando `StaticFiles`.
+/// tip | Dica
+
+Se vocĂȘ precisar hospedar um frontend, use `app.frontend()` em vez disso, leia sobre isso em [Frontend](frontend.md).
+
+`app.frontend()` usa `StaticFiles` por baixo, com vĂĄrias vantagens adicionais para frontends, como lidar com roteamento do lado do cliente.
+
+///
+
## Use `StaticFiles` { #use-staticfiles }
* Importe `StaticFiles`.
/// tip | Dica
-Se vocĂȘ quiser chamar funçÔes `async` em seus testes alĂ©m de enviar solicitaçÔes Ă sua aplicação FastAPI (por exemplo, funçÔes de banco de dados assĂncronas), dĂȘ uma olhada em [Testes assĂncronos](../advanced/async-tests.md) no tutorial avançado.
+Se vocĂȘ quiser chamar funçÔes `async` em seus testes alĂ©m de enviar requests Ă sua aplicação FastAPI (por exemplo, funçÔes de banco de dados assĂncronas), dĂȘ uma olhada em [Testes assĂncronos](../advanced/async-tests.md) no tutorial avançado.
///
{* ../../docs_src/app_testing/app_a_py310/test_main.py hl[3] *}
+
...e ter o cĂłdigo para os testes como antes.
## Testando: exemplo estendido { #testing-extended-example }
â  âââ test_main.py
```
-Digamos que agora o arquivo `main.py` com sua aplicação **FastAPI** tenha algumas outras **operaçÔes de rotas**.
+Digamos que agora o arquivo `main.py` com sua aplicação **FastAPI** tenha algumas outras **operaçÔes de rota**.
Ele tem uma operação `GET` que pode retornar um erro.
Ele tem uma operação `POST` que pode retornar vårios erros.
-Ambas as *operaçÔes de rotas* requerem um cabeçalho `X-Token`.
+Ambas as *operaçÔes de rota* requerem um cabeçalho `X-Token`.
{* ../../docs_src/app_testing/app_b_an_py310/main.py *}
{* ../../docs_src/app_testing/app_b_an_py310/test_main.py *}
+
Sempre que vocĂȘ precisar que o cliente passe informaçÔes na requisição e nĂŁo souber como, vocĂȘ pode pesquisar (no Google) como fazer isso no `httpx`, ou atĂ© mesmo como fazer isso com `requests`, jĂĄ que o design do HTTPX Ă© baseado no design do Requests.
Depois Ă© sĂł fazer o mesmo nos seus testes.
Observe que o `TestClient` recebe dados que podem ser convertidos para JSON, nĂŁo para modelos Pydantic.
-Se vocĂȘ tiver um modelo Pydantic em seu teste e quiser enviar seus dados para o aplicativo durante o teste, poderĂĄ usar o `jsonable_encoder` descrito em [Codificador compatĂvel com JSON](encoder.md).
+Se vocĂȘ tiver um modelo Pydantic em seu teste e quiser enviar seus dados para a aplicação durante o teste, poderĂĄ usar o `jsonable_encoder` descrito em [Codificador compatĂvel com JSON](encoder.md).
///
///
-## Criar um Projeto { #create-a-project }
+## Crie um Projeto { #create-a-project }
Primeiro, crie um diretĂłrio para seu projeto.
////
-## Atualizar `pip` { #upgrade-pip }
+## Atualize `pip` { #upgrade-pip }
/// tip | Dica
///
-## Adicionar `.gitignore` { #add-gitignore }
+## Adicione `.gitignore` { #add-gitignore }
Se vocĂȘ estiver usando **Git** (vocĂȘ deveria), adicione um arquivo `.gitignore` para excluir tudo em seu `.venv` do Git.
///
-## Instalar Pacotes { #install-packages }
+## Instale Pacotes { #install-packages }
ApĂłs ativar o ambiente, vocĂȘ pode instalar pacotes nele.
///
-### Instalar pacotes diretamente { #install-packages-directly }
+### Instale pacotes diretamente { #install-packages-directly }
Se estiver com pressa e nĂŁo quiser usar um arquivo para declarar os requisitos de pacote do seu projeto, vocĂȘ pode instalĂĄ-los diretamente.
////
-### Instalar a partir de `requirements.txt` { #install-from-requirements-txt }
+### Instale a partir de `requirements.txt` { #install-from-requirements-txt }
Se vocĂȘ tiver um `requirements.txt`, agora poderĂĄ usĂĄ-lo para instalar seus pacotes.
///
-## Desativar o ambiente virtual { #deactivate-the-virtual-environment }
+## Desative o ambiente virtual { #deactivate-the-virtual-environment }
Quando terminar de trabalhar no seu projeto, vocĂȘ pode **desativar** o ambiente virtual.
Isso significa que o programa `python` que serĂĄ usado Ă© aquele **no ambiente virtual**.
-vocĂȘ usa `which` no Linux e macOS e `Get-Command` no Windows PowerShell.
+VocĂȘ usa `which` no Linux e macOS e `Get-Command` no Windows PowerShell.
A maneira como esse comando funciona Ă© que ele vai e verifica na variĂĄvel de ambiente `PATH`, passando por **cada caminho em ordem**, procurando pelo programa chamado `python`. Uma vez que ele o encontre, ele **mostrarĂĄ o caminho** para esse programa.
$ python main.py
-// Erro ao importar o Sirius, ele nĂŁo estĂĄ instalado đ±
+// Erro ao importar sirius, ele nĂŁo estĂĄ instalado đ±
Traceback (most recent call last):
File "main.py", line 1, in <module>
import sirius
Se vocĂȘ leu e entendeu tudo isso, agora **vocĂȘ sabe muito mais** sobre ambientes virtuais do que muitos desenvolvedores por aĂ. đ€
-Saber esses detalhes provavelmente serĂĄ Ăștil no futuro, quando vocĂȘ estiver depurando algo que parece complexo, mas vocĂȘ saberĂĄ **como tudo funciona**. đ
+Saber esses detalhes provavelmente serĂĄ Ăștil no futuro, quando vocĂȘ estiver depurando algo que parece complexo, mas vocĂȘ saberĂĄ **como tudo funciona por baixo**. đ
projects / thirdparty / fastapi / fastapi.git / commitdiff
