Início Rápido: Criar um aplicativo Web do Node.js usando a conta de API de SQL do Azure Cosmos DBQuickstart: Build a Node.js app using Azure Cosmos DB SQL API account

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 documentos, chave/valor e bancos de dados do grafo. Todos se beneficiam de recursos de escala horizontal e distribuição global no núcleo do Azure 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 Azure Cosmos DB.

Este início rápido demonstra como criar uma conta de API do SQL, um banco de dados de documento e um contêiner do Azure Cosmos DB usando o portal do Azure.This quickstart demonstrates how to create an Azure Cosmos DB SQL API account, document database, and container using the Azure portal. Em seguida, crie e execute um aplicativo de console criado no SDK do JavaScript em SQL.You then build and run a console app built on the SQL JavaScript SDK. Este início rápido usa a versão 2.0 do SDK do JavaScript.This quickstart uses version 2.0 of the JavaScript SDK.

Pré-requisitosPrerequisites

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.If you don't have an Azure subscription, create a free account before you begin.

Você pode Experimentar o Azure Cosmos DB gratuitamente sem uma assinatura do Azure, gratuitamente e sem compromisso.You can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. Ou, você pode usar o Emulador do Azure Cosmos DB com um URI de https://localhost:8081.Or, you can use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. A Chave Primária é fornecida nas Solicitações de autenticação.The Primary Key is provided in Authenticating requests.

  • Além disso:In addition:

Criar uma conta de banco de dadosCreate a database 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 contêinerAdd a container

Agora, você pode usar a ferramenta Data Explorer no portal do Azure para criar um banco de dados e um contêiner.You can now use the Data Explorer tool in the Azure portal to create a database and container.

  1. Selecione Data Explorer > Novo Contêiner.Select Data Explorer > New Container.

    A área Adicionar Contêiner é exibida à extrema direita; talvez seja necessário rolar a página para a direita para vê-la.The Add Container area is displayed on the far right, you may need to scroll right to see it.

    O Data Explorer do portal do Azure, painel Adicionar Contêiner

  2. Na página Adicionar contêiner, insira as configurações do novo contêiner.In the Add container page, enter the settings for the new container.

    ConfiguraçãoSetting Valor sugeridoSuggested value DESCRIÇÃODescription
    ID do banco de dadosDatabase ID TarefasTasks 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 do novo contêiner.Enter Items as the name for your new container. As IDs do contêiner têm os mesmos requisitos de caractere dos nomes de bancos de dados.Container 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.

    Além das configurações anteriores, opcionalmente, você pode adicionar Chaves exclusivas ao contêiner.In addition to the preceding settings, you can optionally add Unique keys for the container. Vamos deixar o campo vazio neste exemplo.Let's leave the field empty in this example. As chaves exclusivas oferecem aos desenvolvedores a capacidade de adicionar uma camada de integridade dos dados ao seu banco de dados.Unique keys provide developers with the ability to add a layer of data integrity to the database. Ao criar uma política de chave exclusiva durante a criação de um contêiner, você garante a exclusividade de um ou mais valores por chave de partição.By creating a unique key policy while creating a container, you ensure the uniqueness of one or more values per partition key. Para obter mais informações, consulte o artigo Chaves exclusivas no Azure Cosmos DB.To learn more, refer to the Unique keys in Azure Cosmos DB article.

    Selecione OK.Select OK. O Data Explorer exibe o novo banco de dados e o contêiner.The Data Explorer displays the new database and container.

Adicionar dados de exemploAdd sample data

Agora você pode adicionar dados à sua nova coleção usando o Data Explorer.You can now add data to your new collection using Data Explorer.

  1. No Data Explorer, o novo banco de dados aparece no painel Coleções.In Data Explorer, the new database appears in the Collections pane. Expanda o banco de dados Tarefas, expanda a coleção Itens, clique em Documentos e clique em Novos Documentos.Expand the Tasks database, expand the Items collection, click Documents, and then click New Documents.

    Criar novos documentos no Data Explorer no portal do Azure

  2. Agora, adicione um documento à coleção com a seguinte estrutura.Now add a document to the collection with the following structure.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Depois de ter adicionado o json à guia Documentos, clique em Salvar.Once you've added the json to the Documents tab, click Save.

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

  4. Crie e salve mais um documento onde você insere um valor exclusivo para a propriedade id e altere as outras propriedades quando achar adequado.Create and save one more document where you insert a unique value for the id property, and change the other properties as you see fit. Os novos documentos podem ter qualquer estrutura que você deseje, pois o Azure Cosmos DB não impõe nenhum esquema para seus dados.Your new documents can have any structure you want as 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.

Clonar o aplicativo de exemploClone the sample application

Agora vamos clonar um aplicativo de API do SQL do GitHub, definir a cadeia de conexão e executá-lo.Now let's clone a SQL API app from GitHub, set the connection string, and run it.

  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/azure-cosmos-db-sql-api-nodejs-getting-started.git
    

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 Atualizar sua cadeia de conexão.Otherwise, you can skip ahead to Update your connection string.

Observe que se você estiver familiarizado com a versão anterior do SDK do JavaScript, poderá estar acostumado a ver os termos 'coleção' e 'documento'.Note, if you are familiar with the previous version of the JavaScript SDK, you may be used to seeing the terms 'collection' and 'document.' Como o Azure Cosmos DB dá suporte a vários modelos de API, a versão 2.0 ou superior do SDK do JavaScript usa o termos genéricos 'contêiner', que pode ser uma coleção, um gráfico ou uma tabela, e 'item' para descrever o conteúdo do contêiner.Because Azure Cosmos DB supports multiple API models, version 2.0+ of the JavaScript SDK uses the generic terms 'container', which may be a collection, graph, or table and 'item' to describe the content of the container.

Todos os snippets de código a seguir são retirados do arquivo app.js.The following snippets are all taken from the app.js file.

  • O CosmosClient é inicializado.The CosmosClient is initialized.

    const client = new CosmosClient({ endpoint: endpoint, auth: { masterKey: masterKey } });
    
  • Um novo banco de dados é criado.A new database is created.

    const { database } = await client.databases.createIfNotExists({ id: databaseId });
    
  • É criado um novo contêiner (coleção).A new container (collection) is created.

    const { container } = await client.database(databaseId).containers.createIfNotExists({ id: containerId });
    
  • Um item (documento) é criado.An item (document) is created.

    const { item } = await client.database(databaseId).container(containerId).items.create(itemBody);
    
  • Uma consulta SQL no JSON é executada.A SQL query over JSON is performed.

    const querySpec = {
        query: "SELECT VALUE r.children FROM root r WHERE r.lastName = @lastName",
        parameters: [
            {
                name: "@lastName",
                value: "Andersen"
            }
        ]
    };
    
    const { result: results } = await client.database(databaseId).container(containerId).items.query(querySpec).toArray();
    for (var queryResult of results) {
        let resultString = JSON.stringify(queryResult);
        console.log(`\tQuery returned ${resultString}\n`);
    }
    

Atualizar sua cadeia de conexãoUpdate your connection string

Agora, volte ao portal do Azure para obter informações sobre a cadeia de conexão e copiá-las para o aplicativo.Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. No portal do Azure, em sua conta do Azure Cosmos, no painel de navegação à esquerda, clique em Chaves e, em seguida, clique em Chaves de leitura/gravação.In the Azure portal, in your Azure Cosmos account, in the left navigation click Keys, and then click Read-write Keys. Você usará os botões de cópia no lado direito da tela para copiar o URI e a Chave Primária para o arquivo config.js na próxima etapa.You'll use the copy buttons on the right side of the screen to copy the URI and Primary Key into the config.js file in the next step.

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

  2. Abra o arquivo config.js.In Open the config.js file.

  3. Copie o valor do URI do portal (usando o botão de cópia) e transforme-o no valor da chave do ponto de extremidade em config.js.Copy your URI value from the portal (using the copy button) and make it the value of the endpoint key in config.js.

    config.endpoint = "https://FILLME.documents.azure.com"

  4. Em seguida, copie o valor da CHAVE PRIMÁRIA do portal e transforme-o no valor de config.primaryKey em config.js.Then copy your PRIMARY KEY value from the portal and make it the value of the config.primaryKey in config.js. Agora, você atualizou o aplicativo com todas as informações necessárias para se comunicar com o Azure Cosmos DB.You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

    config.primaryKey = "FILLME"

Execute o aplicativoRun the app

  1. Executar npm install em um terminal para instalar os módulos npm necessáriosRun npm install in a terminal to install required npm modules

  2. Execute node app.js em um terminal para iniciar o aplicativo de nó.Run node app.js in a terminal to start your node application.

Agora, é possível voltar ao Data Explorer e ver a consulta, modificar e trabalhar com esses novos dados.You can now go back to Data Explorer and see query, modify, and work with this new data.

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