Início Rápido: Criar um aplicativo Web do .NET usando a conta da API do SQL no Azure Cosmos DBQuickstart: Build a .NET web app using SQL API account in Azure Cosmos DB

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 usar o Azure Cosmos DB para criar e consultar rapidamente bancos de dados de chave/valor, bancos de dados de documentos e bancos de dados de grafo. Todos se beneficiam de recursos de escala horizontal e distribuição global no núcleo do Azure Cosmos DB.You can use Azure Cosmos DB to quickly create and query key/value databases, document databases, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Este início rápido demonstra como usar o portal do Azure para criar uma conta de API de SQL do Azure Cosmos DB, criar uma coleção e um banco de dados de documentos e adicionar dados à coleção.This quickstart demonstrates how to use the Azure portal to create an Azure Cosmos DB SQL API account, create a document database and collection, and add data to the collection. Você então usa um aplicativo Web de SDK do .NET SQL para adicionar mais dados à coleção.You then use a SQL .NET SDK web app to add more data to the collection.

Neste início rápido, você usa o Data Explorer no portal do Azure para criar o banco de dados e a coleção.In this quickstart, you use Data Explorer in the Azure portal to create the database and collection. Você também pode criar o banco de dados e a coleção usando o código de exemplo do .NET.You can also create the database and collection by using the .NET sample code. Para obter mais informações, veja Examinar o código .NET.To learn more, see Review the .NET code.

Pré-requisitosPrerequisites

Visual Studio 2019 com o fluxo de trabalho de desenvolvimento do Azure instaladoVisual Studio 2019 with the Azure development workflow installed

  • Você pode baixar e usar o Visual Studio 2019 Community Edition gratuito.You can download and use the free Visual Studio 2019 Community Edition. Verifique se você habilitou o desenvolvimento do Azure durante a instalação do Visual Studio.Make sure that you enable Azure development during the Visual Studio setup.

Uma assinatura do Azure ou uma conta de avaliação gratuita do Azure Cosmos DBAn Azure subscription or free Azure Cosmos DB trial account

Criar uma conta do Azure Cosmos DBCreate an Azure Cosmos DB account

  1. Entre no Portal do Azure.Sign in to the Azure portal.

  2. Selecione Criar um recurso > Bancos de dados > Azure Cosmos DB.Select Create a resource > Databases > Azure Cosmos DB.

    O painel Bancos de Dados do portal do Azure

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

    ConfiguraçãoSetting ValorValue DESCRIÇÃODescription
    AssinaturaSubscription Nome da assinaturaSubscription name Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Grupo de recursosResource Group Nome do grupo de recursosResource group name Selecione um grupo de recursos ou selecione Criar novo, então insira um nome exclusivo para o novo grupo de recursos.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nome da contaAccount Name Insira um nome exclusivoEnter a unique name Insira um nome para identificar a conta do Azure Cosmos.Enter a name to identify your Azure Cosmos 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 pode conter apenas letras minúsculas, números e o caractere de hífen (-).The ID can only contain lowercase letters, numbers, and the hyphen (-) character. Ela deve ter entre 3 e 31 caracteres.It must be between 3-31 characters in length.
    APIAPI Núcleo (SQL)Core (SQL) 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: Núcleo (SQL) e MongoDB para dados de documento, Gremlin para dados de grafo, Tabela do Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, 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 Núcleo (SQL) para criar uma consulta e um banco de dados de documento usando a sintaxe SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    Saiba mais sobre a API do SQL.Learn more about the SQL API.
    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 a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.Use the location that is closest to your users to give them the fastest access to the data.

    A página da nova conta do Azure Cosmos DB

  4. Selecione Examinar + criar.Select Review + create. Você pode ignorar as seções Rede e Marcas.You can skip the Network and Tags sections.

  5. Examine as configurações da conta e selecione Criar.Review the account settings, and then select Create. São necessários alguns minutos para criar a conta.It takes a few minutes to create the account. Aguarde até que a página do portal exiba Sua implantação está concluída.Wait for the portal page to display Your deployment is complete.

    O painel Notificações do portal do Azure

  6. Selecione Ir para recurso para ir para a página da conta do Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    A página da conta do Azure Cosmos DB

Adicionar um banco de dados e uma coleçãoAdd a database and a collection

Você pode usar o Data Explorer no portal do Azure para criar um banco de dados e uma coleção.You can use the Data Explorer in the Azure portal to create a database and collection.

  1. Selecione Data Explorer no painel de navegação à esquerda na página de sua conta do Azure Cosmos DB e, em seguida, selecione Novo Contêiner.Select Data Explorer from the left navigation on your Azure Cosmos DB account page, and then select New Container.

    Talvez seja necessário rolar a página para a direita para ver a janela Adicionar Contêiner.You may need to scroll right to see the Add Container window.

    O Data Explorer do portal do Azure, painel Adicionar Coleção

  2. No painel Adicionar contêiner, insira as configurações da nova coleção.In the Add container pane, enter the settings for the new collection.

    ConfiguraçãoSetting Valor sugeridoSuggested value DESCRIÇÃODescription
    ID do banco de dadosDatabase ID ToDoListToDoList Insira ToDoList como o nome para o novo banco de dados.Enter ToDoList as the name for the new database. Os nomes dos banco de dados devem conter de 1 a 255 caracteres e não podem conter /, \\, #, ? nem um espaço à direita.Database names must contain from 1 through 255 characters, and they cannot contain /, \\, #, ?, or a trailing space. Marque a opção Provisionar a produtividade do banco de dados; ela permite que você compartilhe a produtividade provisionada para o banco de dados em todos os contêineres no banco de dados.Check the Provision database throughput option, it allows you to share the throughput provisioned to the database across all the containers within the database. Essa opção também ajuda na economia de custo.This option also helps with cost savings.
    Taxa de transferênciaThroughput 400400 Deixe a taxa de transferência em 400 unidades de solicitação por segundo (RU/s).Leave the throughput at 400 request units per second (RU/s). Se quiser reduzir a latência, você poderá escalar verticalmente a taxa de transferência mais tarde.If you want to reduce latency, you can scale up the throughput later.
    ID do contêinerContainer ID ItensItems Insira Itens como o nome da nova coleção.Enter Items as the name for your new collection. As IDs da coleção possuem os mesmos requisitos de caractere que os nomes de bancos de dados.Collection IDs have the same character requirements as database names.
    Chave de partiçãoPartition key /category/category O exemplo descrito neste artigo usa /category como a chave de partição.The sample described in this article uses /category as the partition key.

    Não adicione Chaves exclusivas para este exemplo.Don't add Unique keys for this example. Chaves exclusivas permitem que você adicione uma camada de integridade de dados ao banco de dados garantindo a exclusividade de um ou mais valores por chave de partição.Unique keys let you add a layer of data integrity to the database by ensuring the uniqueness of one or more values per partition key. Para obter mais informações, veja Chaves exclusivas no Azure Cosmos DB.For more information, see Unique keys in Azure Cosmos DB.

  3. Selecione OK.Select OK. O Data Explorer exibe o novo banco de dados e o contêiner que você criou.The Data Explorer displays the new database and the container that you created.

Adicionar dados a seu banco de dadosAdd data to your database

Adicione dados a seu novo banco de dados usando o Data Explorer.Add data to your new database using Data Explorer.

  1. No Data Explorer, expanda o banco de dados ToDoList e, em seguida, expanda o contêiner Itens.In Data Explorer, expand the ToDoList database, and expand the Items container. Em seguida, selecione Itens e, em seguida, selecione Novo Item.Next, select Items, and then select New Item.

    Criar novos documentos no Data Explorer no portal do Azure

  2. Adicione a seguinte estrutura ao documento no lado direito do painel Documentos:Add the following structure to the document on the right side of the Documents pane:

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Clique em Salvar.Select Save.

    Copie nos dados json e selecione em Salvar no Data Explorer no portal do Azure

  4. Selecione Novo Documento novamente e crie e salve um outro documento com uma única id e quaisquer outras propriedades e valores desejados.Select New Document again, and create and save another document with a unique id, and any other properties and values you want. Os documentos podem ter qualquer estrutura, pois o Azure Cosmos DB não impõe nenhum esquema a seus dados.Your documents can have any structure, because Azure Cosmos DB doesn't impose any schema on your data.

Consultar seus dadosQuery your data

Você pode usar consultas no Data Explorer para recuperar e filtrar os dados.You can use queries in Data Explorer to retrieve and filter your data.

  1. Na parte superior da guia Documentos no Data Explorer, examine a consulta padrão SELECT * FROM c.At the top of the Documents tab in Data Explorer, review the default query SELECT * FROM c. Essa consulta recupera e exibe todos os documentos na coleção na ordem da ID.This query retrieves and displays all documents in the collection in ID order.

    A consulta padrão no Data Explorer é SELECT * FROM c

  2. Para alterar a consulta, selecione Editar Filtro, substitua a consulta padrão por ORDER BY c._ts DESC e selecione Aplicar Filtro.To change the query, select Edit Filter, replace the default query with ORDER BY c._ts DESC, and then select Apply Filter.

    Altere a consulta padrão adicionando ORDER BY c._ts DESC e clicando Aplicar Filtro

    A consulta modificada exibe os documentos em ordem decrescente com base em seu carimbo de data/hora, portanto, agora o segundo documento é listado primeiro.The modified query displays the documents in descending order based on their time stamp, so now your second document is listed first.

    Alterada a consulta para ORDER BY c._ts DESC e clicando em Aplicar Filtro

Se você estiver familiarizado com a sintaxe SQL, poderá inserir qualquer consulta SQL compatível na caixa de predicado de consulta.If you're familiar with SQL syntax, you can enter any supported SQL queries in the query predicate box. Você também pode usar o Data Explorer para criar procedimentos armazenados, UDFs e gatilhos para lógica de negócios do lado do servidor.You can also use Data Explorer to create stored procedures, UDFs, and triggers for server-side business logic.

O Data Explorer fornece acesso fácil ao portal do Azure para todos os recursos de acesso a dados programático interno por disponível nas APIs.Data Explorer provides easy Azure portal access to all of the built-in programmatic data access features available in the APIs. Você também pode usar o portal para dimensionar a taxa de transferência, obter as chaves e as cadeias de conexão e examinar as métricas e os SLAs para sua conta do Azure Cosmos DB.You also use the portal to scale throughput, get keys and connection strings, and review metrics and SLAs for your Azure Cosmos DB account.

Use o aplicativo Web do .NET para gerenciar dadosUse the .NET web app to manage data

Para ver como é fácil trabalhar com seus dados do Azure Cosmos DB de modo programático, clone o aplicativo Web do .NET da API SQL de exemplo do GitHub, atualize a cadeia de conexão e execute o aplicativo para atualizar seus dados.To see how easy it is to work with your Azure Cosmos DB data programmatically, clone the sample SQL API .NET web app from GitHub, update the connection string, and run the app to update your data.

Você também pode criar o banco de dados e o contêiner usando o código de exemplo do .NET.You could also create the database and the container by using the .NET sample code. Para obter mais informações, veja Examinar o código .NET.To learn more, see Review the .NET code.

Clonar o aplicativo de exemploClone the sample app

Primeiro, clone um aplicativo de API do SQL em C# do GitHub.First, clone a C# SQL API app from GitHub.

  1. Abra uma janela do terminal do git, como Git Bash, crie um diretório chamado git-samples e altere-o para:Open a git terminal window, such as Git Bash, create a new directory named git-samples, and change to it:

    mkdir /c/git-samples/
    cd /c/git-samples/
    
  2. Execute o seguinte comando para clonar o repositório de exemplo e criar uma cópia do aplicativo de exemplo em seu computador:Run the following command to clone the sample repository and create a copy of the sample app on your computer:

    git clone https://github.com/Azure-Samples/documentdb-dotnet-todo-app.git
    

Atualizar a cadeia de conexãoUpdate the connection string

  1. Navegue até o arquivo todo.sln e abra-o de seu aplicativo clonado no Visual Studio.Navigate to and open the todo.sln file of your cloned app in Visual Studio.

  2. No Gerenciador de Soluções do Visual Studio, abra o arquivo web.config.In Visual Studio Solution Explorer, open the web.config file.

  3. Volte para o portal do Azure para copiar as informações de sua cadeia de conexão para colar em web.config.Go back to the Azure portal to copy your connection string information to paste into the web.config.

    1. Na navegação esquerda de sua conta do Azure Cosmos DB, selecione Chaves.In your Azure Cosmos DB account left navigation, select Keys.

      Exibir e copiar uma chave de acesso no Portal do Azure, folha Chaves

    2. Em Chaves de Leitura/Gravação, copie o valor do URI usando o botão de copiar à direita e, em seguida, cole-o na chave endpoint em web.config. Por exemplo:Under Read-write Keys, copy the URI value using the copy button at the right, and paste it into the endpoint key in the web.config. For example:

      <add key="endpoint" value="https://mysqlapicosmosdb.documents.azure.com:443/" />

    3. Copie o valor em CHAVE PRIMÁRIA e cole-o na chave authKey em web.config. Por exemplo:Copy the PRIMARY KEY value and paste it into the authKey key in the web.config. For example:

      <add key="authKey" value="19ZDNJAiYL26tmnRvoez6hmtIfBGwjun50PWRjNYMC2ig8Ob9hYk7Fq1RYSv8FcIYnh1TdBISvCh7s6yyb0000==" />

  4. Verifique se os valores do banco de dados e da coleção (também chamada contêiner) no web.config correspondem aos nomes que você criou anteriormente.Make sure the database and collection (also called container) values in the web.config match the names you created earlier.

    <add key="database" value="ToDoList"/>
    <add key="collection" value="Items"/>
    
  5. Salve o web.config. Agora, você atualizou o aplicativo com todas as informações necessárias para se comunicar com o Azure Cosmos DB.Save the web.config. You've now updated your app with all the information it needs to communicate with Azure Cosmos DB.

Executar o aplicativo WebRun the web app

  1. No Visual Studio, clique com o botão direito do mouse no projeto todo no Gerenciador de Soluções e selecione Gerenciar Pacotes do NuGet.In Visual Studio, right-click the todo project in Solution Explorer, and then select Manage NuGet Packages.

  2. Na caixa Procurar do NuGet, digite DocumentDB.In the NuGet Browse box, type DocumentDB.

  3. Nos resultados, instale a versão 2.2.3 da biblioteca Microsoft.Azure.DocumentDB se ainda não estiver instalada.From the results, install the 2.2.3 version of Microsoft.Azure.DocumentDB library if not already installed. Isso instala o pacote Microsoft.Azure.DocumentDB e todas as dependências.This installs the Microsoft.Azure.DocumentDB package and all dependencies.

    Se o NuGet Package Manager exibir uma mensagem de que alguns pacotes estão ausentes da solução, selecione Restaurar para instalá-los de fontes internas.If the NuGet Package Manager displays a message that some packages are missing from the solution, select Restore to install them from internal sources.

  4. Selecione Ctrl+F5 para executar o aplicativo em seu navegador.Select Ctrl+F5 to run the app in your browser.

  5. Selecione Criar Novo no aplicativo de tarefas pendentes e crie algumas tarefas.Select Create New in the to-do app, and create a few new tasks.

    Aplicativo de tarefas pendentes com os dados de exemplo

Agora é possível voltar ao Data Explorer no portal do Azure para ver, consultar, modificar e trabalhar com seus novos dados.You can go back to Data Explorer in the Azure portal to see, query, modify, and work with your new data.

Examinar o código do .NETReview the .NET code

Esta etapa é opcional.This step is optional. Neste início rápido, você criou um banco de dados e um contêiner no portal do Azure e adicionou dados de exemplo usando a amostra do .NET.In this quickstart, you created a database and a container in the Azure portal and added sample data by using the .NET sample. No entanto, você também pode criar o banco de dados e o contêiner usando a amostra do .NET.However, you can also create the database and the container by using the .NET sample. Examine os snippets de código a seguir se você estiver interessado em como os recursos de banco de dados são criados no código.Review the following snippets if you're interested in how database resources are created in the code. Os snippets de código são todos obtidos do arquivo DocumentDBRepository.cs no projeto todo.The snippets are all taken from the DocumentDBRepository.cs file in the todo project.

  • Esse código inicializa o DocumentClient:This code initializes the DocumentClient:

    client = new DocumentClient(new Uri(ConfigurationManager.AppSettings["endpoint"]), ConfigurationManager.AppSettings["authKey"]);
    
  • Esse código cria o novo banco de dados usando o método CreateDatabaseAsync:This code creates the new database by using the CreateDatabaseAsync method:

    await client.CreateDatabaseAsync(new Database { Id = DatabaseId });
    
  • O código a seguir cria a nova coleção usando o método CreateDocumentCollectionAsync:The following code creates the new collection by using the CreateDocumentCollectionAsync method:

    private static async Task CreateCollectionIfNotExistsAsync(string partitionkey)
    {
       try
       {       
        await client.ReadDocumentCollectionAsync(UriFactory.CreateDocumentCollectionUri(DatabaseId, CollectionId), new RequestOptions { PartitionKey = new PartitionKey(partitionkey) });
       }
        catch (DocumentClientException e)
        {
           if (e.StatusCode == System.Net.HttpStatusCode.NotFound)
            {
                await client.CreateDocumentCollectionAsync(
                  UriFactory.CreateDatabaseUri(DatabaseId),
                   new DocumentCollection
                    {
                      Id = CollectionId,
                      PartitionKey = new PartitionKeyDefinition
                       {
                           Paths = new System.Collections.ObjectModel.Collection<string>(new List<string>() { partitionkey })
                        }
                    },
                      new RequestOptions { OfferThroughput = 400 });
            }
            else
            {
                throw;
            }
        }
    }
    

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 a criar uma conta do Azure Cosmos DB, criar um banco de dados e um contêiner usando o Data Explorer e executar um aplicativo Web .NET para atualizar seus dados.In this quickstart, you learned how to create an Azure Cosmos DB account, create a database and container using the Data Explorer, and run a .NET web app to update your data. Agora, é possível importar outros dados para sua conta do Azure Cosmos DB.You can now import additional data to your Azure Cosmos DB account.