Início Rápido: Criar um aplicativo do Python usando a API para MongoDB do Azure Cosmos DBQuickstart: Build a Python app using Azure Cosmos DB's API for MongoDB

O Azure Cosmos DB é o serviço de banco de dados multimodelo distribuído globalmente da Microsoft.Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. É possível criar e consultar rapidamente bancos de dados de documentos, de chave/valor e de grafo, que se beneficiem das funcionalidades de escala horizontal e distribuição global no núcleo do Cosmos DB.You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Cosmos DB.

Este guia de início rápido, usa o seguinte exemplo do Flask e demonstra como criar um aplicativo Flask simples de tarefas pendentes usando o Emulador do Azure Cosmos DB e a API para MongoDB do Azure Cosmos DB.This quickstart guide uses the following Flask example and demonstrates how to build a simple To-Do Flask app with the Azure Cosmos DB Emulator and the Azure Cosmos DB's API for MongoDB.

Pré-requisitosPrerequisites

  • Baixe o Emulador do Azure Cosmos DB.Download the Azure Cosmos DB Emulator. No momento, o emulador é compatível apenas no Windows.The emulator is currently only supported on Windows. O exemplo mostra como usar o exemplo com uma chave de produção do Azure, o que pode ser feito em qualquer plataforma.The sample shows how to use the sample with a production key from Azure, which can be done on any platform.

  • Se você ainda não tiver o Visual Studio Code instalado, instale rapidamente o VS Code para sua plataforma (Windows, Mac, Linux).If you don’t already have Visual Studio Code installed, you can quickly install VS Code for your platform (Windows, Mac, Linux).

  • Lembre-se de adicionar o suporte à linguagem Python ao instalar uma das extensões do Python populares.Be sure to add Python Language support by installing one of the popular Python extensions.

    1. Selecione uma extensão.Select an extension.

    2. Instale a extensão digitando ext install na paleta de comandos Ctrl+Shift+P.Install the extension by typing ext install into the Command Palette Ctrl+Shift+P.

      Os exemplos neste documento usam a popular e completa Extensão do Python do Don Jayamanne.The examples in this document use Don Jayamanne's popular and full featured Python Extension.

Clonar o aplicativo de exemploClone the sample application

Agora vamos clonar um aplicativo Flask-MongoDB do GitHub, definir a cadeia de conexão e executá-lo.Now let's clone a Flask-MongoDB app from GitHub, set the connection string, and run it. Você verá como é fácil trabalhar usando dados de forma programática.You see how easy it is to work with data programmatically.

  1. Abra um prompt de comando, crie uma nova pasta chamada exemplos de git e feche o prompt de comando.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. Abra uma janela de terminal de git, como git bash, e use o comando cd para alterar para a nova pasta para instalar o aplicativo de exemplo.Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. Execute o comando a seguir para clonar o repositório de exemplo.Run the following command to clone the sample repository. Este comando cria uma cópia do aplicativo de exemplo no seu computador.This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/CosmosDB-Flask-Mongo-Sample.git
    
  4. Execute o seguinte comando para instalar os módulos do Python.Run the following command to install the python modules.

    pip install -r .\requirements.txt
    
  5. Abra a pasta no Visual Studio Code.Open the folder in Visual Studio Code.

Examine o códigoReview the code

Esta etapa é opcional.This step is optional. Se você estiver interessado em aprender como os recursos de banco de dados são criados no código, poderá examinar os snippets de código a seguir.If you're interested in learning how the database resources are created in the code, you can review the following snippets. Caso contrário, você poderá pular para Executar o aplicativo Web.Otherwise, you can skip ahead to Run the web app.

Os snippets de código a seguir são obtidos do arquivo app.py e usam a cadeia de conexão para o Emulador do Azure Cosmos DB.The following snippets are all taken from the app.py file and uses the connection string for the local Azure Cosmos DB Emulator. A senha deve ser dividida da maneira mostrada abaixo para acomodar as barras "/" que não podem ser analisadas de nenhuma outra maneira.The password needs to be split up as seen below to accommodate for the forward slashes that cannot be parsed otherwise.

  • Inicialize o cliente MongoDB, recupere o banco de dados e autentique-se.Initialize the MongoDB client, retrieve the database, and authenticate.

    client = MongoClient("mongodb://127.0.0.1:10250/?ssl=true") #host uri
    db = client.test    #Select the database
    db.authenticate(name="localhost",password='C2y6yDjf5' + r'/R' + '+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw' + r'/Jw==')
    
  • Recupere a coleção ou crie-a se ela ainda não existir.Retrieve the collection or create it if it does not already exist.

    todos = db.todo #Select the collection
    
  • Crie o aplicativoCreate the app

    app = Flask(__name__)
    title = "TODO with Flask"
    heading = "ToDo Reminder"
    

Executar o aplicativo WebRun the web app

  1. Verifique se o emulador do Azure Cosmos DB está em execução.Make sure the Azure Cosmos DB Emulator is running.

  2. Abra uma janela do terminal e emita cd para o diretório no qual o aplicativo está salvo.Open a terminal window and cd to the directory that the app is saved in.

  3. Em seguida, defina a variável de ambiente para o aplicativo Flask com set FLASK_APP=app.py, $env:FLASK_APP = app.py para editores do PowerShell ou export FLASK_APP=app.py se você estiver usando um Mac.Then set the environment variable for the Flask app with set FLASK_APP=app.py, $env:FLASK_APP = app.py for PowerShell editors, or export FLASK_APP=app.py if you are using a Mac.

  4. Execute o aplicativo com flask run e navegue até http://127.0.0.1:5000/.Run the app with flask run and browse to http://127.0.0.1:5000/.

  5. Adicione e remova tarefas e veja-as adicionadas e alteradas na coleção.Add and remove tasks and see them added and changed in the collection.

Criar uma conta de banco de dadosCreate a database account

  1. Em uma nova janela, entre no portal do Azure.In a new window, sign in to the Azure portal.

  2. No menu à esquerda, clique em Criar um recurso, clique em Bancos de dados e depois em Azure Cosmos DB, clique em Criar.In the left menu, click Create a resource, click Databases, and then under Azure Cosmos DB, click Create.

    Captura de tela do Portal do Azure, realçando Mais Serviços e Azure Cosmos DB

  3. Na página Criar Conta do Azure Cosmos DB, insira as configurações da nova conta do Azure Cosmos DB.In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    ConfiguraçãoSetting ValorValue DESCRIÇÃODescription
    AssinaturaSubscription Sua assinaturaYour subscription Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Grupo de recursosResource Group Criar NovoCreate new

    Em seguida, insira o mesmo nome exclusivo fornecido na IDThen enter the same unique name as provided in ID
    Selecione Criar novo.Select Create new. Insira o novo nome do grupo de recursos para sua conta.Then enter a new resource-group name for your account. Para simplificar, use um nome igual à sua ID.For simplicity, use the same name as your ID.
    Nome da contaAccount Name Insira um nome exclusivoEnter a unique name Insira um nome exclusivo para identificar a conta do Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account. Como documents.Azure.com é acrescentado à ID que você fornece para criar o URI, use uma ID exclusiva.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    A ID deve conter apenas letras minúsculas, números e o caractere de hífen (-).The ID can use only lowercase letters, numbers, and the hyphen (-) character. Ela precisa ter entre 3 e 31 caracteres.It must be between 3 and 31 characters in length.
    APIAPI API do Azure Cosmos DB para MongoDBAzure Cosmos DB's API for MongoDB A API determina o tipo de conta a ser criada.The API determines the type of account to create. O Azure Cosmos DB fornece cinco APIs: Core (SQL) para bancos de dados de documentos, Gremlin para o bancos de dados de grafos, API para MongoDB do Azure Cosmos DB para bancos de dados de documentos, Tabela do Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) for document databases, Gremlin for graph databases, Azure Cosmos DB's API MongoDB for document databases, Azure Table, and Cassandra. No momento, você deve criar uma conta separada para cada API.Currently, you must create a separate account for each API.

    Selecione MongoDB, porque neste guia de início rápido você está criando uma tabela que funciona com o MongoDB.Select MongoDB because in this quickstart you are creating a table that works with the MongoDB.
    Local padrãoLocation Selecione a região mais próxima de seus usuáriosSelect the region closest to your users Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use o local mais próximo dos usuários para fornecer a eles acesso mais rápido aos dados.Use the location that's closest to your users to give them the fastest access to the data.

    Selecione Revisar + Criar.Select Review+Create. Você pode ignorar as seções Rede e Marcas.You can skip the Network and Tags section.

    A página da nova conta do Azure Cosmos DB

  4. A criação da conta leva alguns minutos.The account creation takes a few minutes. Aguarde até que o portal exiba a página Parabéns! Sua conta do Cosmos com a compatibilidade de protocolo de transmissão para o MongoDB está pronta.Wait for the portal to display the Congratulations! Your Cosmos account with wire protocol compatibility for MongoDB is ready page.

    O painel Notificações do portal do Azure

Atualizar sua cadeia de conexãoUpdate your connection string

Se você quiser testar o código em relação a uma conta ativa do Cosmos, acesse o portal do Azure para criar uma conta e obter as informações da cadeia de conexão.If you want to test the code against a live Cosmos Account, go to the Azure portal to create an account and get your connection string information. Em seguida, copie-a no aplicativo.Then copy it into the app.

  1. No portal do Azure, na sua conta do Cosmos, no painel de navegação esquerdo, clique em Cadeia de Conexão e, em seguida, clique em Chaves de leitura/gravação.In the Azure portal, in your Cosmos account, in the left navigation click Connection String, and then click Read-write Keys. Você usará os botões de cópia no lado direito da tela para copiar o Nome de usuário, Senha e Host para o arquivo Dal.cs na próxima etapa.You'll use the copy buttons on the right side of the screen to copy the Username, Password, and Host into the Dal.cs file in the next step.

  2. Abra o arquivo app.py no diretório raiz.Open the app.py file in the root directory.

  3. Copie o valor de nome de usuário do portal (usando o botão de cópia) e cole-o como o valor de nome no arquivo app.py.Copy your username value from the portal (using the copy button) and make it the value of the name in your app.py file.

  4. Em seguida, copie o valor de cadeia de conexão do portal e cole-o como o valor de MongoClient no arquivo app.py.Then copy your connection string value from the portal and make it the value of the MongoClient in your app.py file.

  5. Finalmente copie o valor de senha do portal e cole-o como o valor de senha no arquivo app.py.Finally copy your password value from the portal and make it the value of the password in your app.py file.

Agora, você atualizou o aplicativo com todas as informações necessárias para comunicar-se com o Cosmos DB.You've now updated your app with all the info it needs to communicate with Cosmos DB. É possível executá-lo da mesma forma que antes.You can run it the same way as before.

Implantar no AzureDeploy to Azure

Para implantar esse aplicativo, você pode criar um novo aplicativo Web no Azure e habilitar a implantação contínua com um fork deste repositório do GitHub.To deploy this app, you can create a new web app in Azure and enable continuous deployment with a fork of this GitHub repo. Siga este tutorial para configurar a implantação contínua com o GitHub no Azure.Follow this tutorial to set up continuous deployment with GitHub in Azure.

Ao implantar no Azure, você deve remover as chaves do aplicativo e verificar se a seção abaixo não está comentada:When deploying to Azure, you should remove your application keys and make sure the section below is not commented out:

    client = MongoClient(os.getenv("MONGOURL"))
    db = client.test    #Select the database
    db.authenticate(name=os.getenv("MONGO_USERNAME"),password=os.getenv("MONGO_PASSWORD"))

Em seguida, você precisa adicionar as suas informações de MONGOURL, MONGO_PASSWORD e MONGO_USERNAME nas configurações do aplicativo.You then need to add your MONGOURL, MONGO_PASSWORD, and MONGO_USERNAME to the application settings. Você pode seguir este tutorial para saber mais sobre as configurações de aplicativo em aplicativos Web do Azure.You can follow this tutorial to learn more about Application Settings in Azure Web Apps.

Se você não quiser criar um fork deste repositório, clique no botão Implantar no Azure abaixo.If you don't want to create a fork of this repo, you can also click the deploy to Azure button below. Em seguida, entre no Azure e defina as configurações do aplicativo com as informações da sua conta do Cosmos DB.You should then go into Azure and set up the application settings with your Cosmos DB account info.

Click to Deploy to Azure

Observação

Se você planeja armazenar o código no GitHub ou em outras opções de controle do código-fonte, lembre-se de remover as cadeias de conexão do código. Nesse caso, elas podem ser definidas com as configurações do aplicativo Web.

Examinar SLAs no Portal do AzureReview SLAs in the Azure portal

O portal do Azure monitora a taxa de transferência, armazenamento, disponibilidade, latência e consistência da conta do Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Gráficos de métricas associados a um SLA (Contrato de Nível de Serviço) do Azure Cosmos DB mostram o valor do SLA em comparação com o desempenho real.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Esse conjunto de métricas torna o monitoramento dos SLAs transparente.This suite of metrics makes monitoring your SLAs transparent.

Para examinar as métricas e os SLAs:To review metrics and SLAs:

  1. Selecione Métricas no menu de navegação da sua conta do Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Selecione uma guia, tal como Latência, e selecione um período à direita.Select a tab such as Latency, and select a timeframe on the right. Comparar as linhas Real e SLA dos gráficos.Compare the Actual and SLA lines on the charts.

    Pacote de métricas do Azure Cosmos DB

  3. Examine as métricas nas outras guias.Review the metrics on the other tabs.

Limpar recursosClean up resources

Quando você concluir seu aplicativo Web e a conta do Azure Cosmos DB, poderá excluir os recursos do Azure criados para não incorrer em mais cobranças.When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Para excluir os recursos:To delete the resources:

  1. No portal do Azure, selecione Grupos de recursos no canto esquerdo.In the Azure portal, select Resource groups on the far left. Se o menu esquerdo estiver recolhido, selecione Expandir botão para expandi-lo.If the left menu is collapsed, select Expand button to expand it.

  2. Selecione o grupo de recursos que você criou para este início rápido.Select the resource group you created for this quickstart.

    Métricas no portal do Azure

  3. Na nova janela, selecione Excluir grupo de recursos.In the new window, select Delete resource group.

    Métricas no portal do Azure

  4. Na próxima janela, digite o nome do grupo de recursos a ser excluído e selecione Excluir.In the next window, type the name of the resource group to delete, and then select Delete.

Próximas etapasNext steps

Neste início rápido, você aprendeu como criar uma conta do Cosmos e executar um aplicativo Flask.In this quickstart, you've learned how to create a Cosmos account and run a Flask app. Agora você pode importar dados adicionais para o banco de dados Cosmos.You can now import additional data to your Cosmos database.