Guia de início rápido: implantar o aplicativo de API RESTful no Azure Spring Apps

Nota

Os planos Basic, Standard e Enterprise serão preteridos a partir de meados de março de 2025, com um período de aposentadoria de 3 anos. Recomendamos a transição para os Aplicativos de Contêiner do Azure. Para obter mais informações, consulte o anúncio de aposentadoria do Azure Spring Apps.

O plano de consumo padrão e dedicado será preterido a partir de 30 de setembro de 2024, com um desligamento completo após seis meses. Recomendamos a transição para os Aplicativos de Contêiner do Azure. Para obter mais informações, consulte Migrar consumo padrão e plano dedicado do Azure Spring Apps para Aplicativos de Contêiner do Azure.

Este artigo descreve como implantar um aplicativo de API RESTful protegido pelo Microsoft Entra ID no Azure Spring Apps. O projeto de exemplo é uma versão simplificada baseada no aplicativo Web Simple Todo , que fornece apenas o serviço de back-end e usa o Microsoft Entra ID para proteger as APIs RESTful.

Essas APIs RESTful são protegidas pela aplicação de RBAC (controle de acesso baseado em função). Os utilizadores anónimos não podem aceder a quaisquer dados e não têm permissão para controlar o acesso de diferentes utilizadores. Os utilizadores anónimos têm apenas as três permissões seguintes:

• Leia: Com essa permissão, um usuário pode ler os dados do ToDo.
• Gravação: Com essa permissão, um usuário pode adicionar ou atualizar os dados ToDo.
• Excluir: Com essa permissão, um usuário pode excluir os dados ToDo.

Depois que a implantação for bem-sucedida, você poderá exibir e testar as APIs por meio da interface do usuário do Swagger.

O diagrama a seguir mostra a arquitetura do sistema:

Este artigo descreve as seguintes opções para criar recursos e implantá-los no Azure Spring Apps:

• A opção de plug-in do portal do Azure + Maven fornece uma maneira mais convencional de criar recursos e implantar aplicativos passo a passo. Essa opção é adequada para desenvolvedores do Spring que usam os serviços de nuvem do Azure pela primeira vez.
• A opção CLI do Desenvolvedor do Azure é uma maneira mais eficiente de criar recursos e implantar aplicativos automaticamente por meio de comandos simples. A CLI do Desenvolvedor do Azure usa um modelo para provisionar os recursos do Azure necessários e implantar o código do aplicativo. Essa opção é adequada para desenvolvedores do Spring que estão familiarizados com os serviços de nuvem do Azure.

Este artigo descreve as seguintes opções para criar recursos e implantá-los no Azure Spring Apps:

• A opção de plug-in do portal do Azure + Maven fornece uma maneira mais convencional de criar recursos e implantar aplicativos passo a passo. Essa opção é adequada para desenvolvedores do Spring que usam os serviços de nuvem do Azure pela primeira vez.
• A opção CLI do Azure usa uma poderosa ferramenta de linha de comando para gerenciar recursos do Azure. Essa opção é adequada para desenvolvedores do Spring que estão familiarizados com os serviços de nuvem do Azure.

1. Pré-requisitos

Portal do Azure + plug-in Maven

• Uma subscrição do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

• Uma das seguintes funções:

  • Administrador Global ou Administrador de Funções Privilegiadas para conceder consentimento para aplicações que pedem qualquer permissão, para qualquer API.
  • Cloud Application Administrator ou Application Administrator, por conceder consentimento para aplicativos que solicitam qualquer permissão para qualquer API, exceto funções de aplicativo do Microsoft Graph (permissões de aplicativo).
  • Uma função de diretório personalizada que inclui a permissão para conceder permissões a aplicativos, para as permissões exigidas pelo aplicativo.

  Para obter mais informações, consulte Conceder consentimento de administrador de todo o locatário para um aplicativo.

• Se você estiver implantando uma instância do plano do Azure Spring Apps Enterprise pela primeira vez na assinatura de destino, consulte a seção Requisitos do plano Enterprise no Azure Marketplace.

• Git.

• Java Development Kit (JDK), versão 17.

• Um locatário do Microsoft Entra. Para obter instruções sobre como criar um, consulte Guia de início rápido: criar um novo locatário no Microsoft Entra ID.

CLI do Azure

• Uma assinatura do Azure, Se você não tiver uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

• Uma das seguintes funções:

  • Administrador Global ou Administrador de Funções Privilegiadas para conceder consentimento para aplicações que pedem qualquer permissão, para qualquer API.
  • Cloud Application Administrator ou Application Administrator, por conceder consentimento para aplicativos que solicitam qualquer permissão para qualquer API, exceto funções de aplicativo do Microsoft Graph (permissões de aplicativo).
  • Uma função de diretório personalizada que inclui a permissão para conceder permissões a aplicativos, para as permissões exigidas pelo aplicativo.

  Para obter mais informações, consulte Conceder consentimento de administrador de todo o locatário para um aplicativo.

• Se você estiver implantando uma instância do plano do Azure Spring Apps Enterprise pela primeira vez na assinatura de destino, consulte a seção Requisitos do plano Enterprise no Azure Marketplace.

• Git.

• Java Development Kit (JDK), versão 17.

• Um locatário do Microsoft Entra. Para obter instruções sobre como criar um, consulte Guia de início rápido: criar um novo locatário no Microsoft Entra ID.

• Azure CLI versão 2.53.1 ou superior.

Portal do Azure + plug-in Maven

• Uma assinatura do Azure, Se você não tiver uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

• Uma das seguintes funções:

  • Administrador Global ou Administrador de Funções Privilegiadas para conceder consentimento para aplicações que pedem qualquer permissão, para qualquer API.
  • Cloud Application Administrator ou Application Administrator, por conceder consentimento para aplicativos que solicitam qualquer permissão para qualquer API, exceto funções de aplicativo do Microsoft Graph (permissões de aplicativo).
  • Uma função de diretório personalizada que inclui a permissão para conceder permissões a aplicativos, para as permissões exigidas pelo aplicativo.

  Para obter mais informações, consulte Conceder consentimento de administrador de todo o locatário para um aplicativo.

• Git.

• Java Development Kit (JDK), versão 17.

• Um locatário do Microsoft Entra. Para obter instruções sobre como criar um, consulte Guia de início rápido: criar um novo locatário no Microsoft Entra ID.

CLI do desenvolvedor do Azure

• Uma assinatura do Azure, Se você não tiver uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

• Uma das seguintes funções:

  • Administrador Global ou Administrador de Funções Privilegiadas para conceder consentimento para aplicações que pedem qualquer permissão, para qualquer API.
  • Cloud Application Administrator ou Application Administrator, por conceder consentimento para aplicativos que solicitam qualquer permissão para qualquer API, exceto funções de aplicativo do Microsoft Graph (permissões de aplicativo).
  • Uma função de diretório personalizada que inclui a permissão para conceder permissões a aplicativos, para as permissões exigidas pelo aplicativo.

  Para obter mais informações, consulte Conceder consentimento de administrador.

• Git.

• Java Development Kit (JDK), versão 17.

• Um locatário do Microsoft Entra. Para obter instruções sobre como criar um, consulte Guia de início rápido: criar um novo locatário no Microsoft Entra ID.

• Azure Developer CLI (AZD), versão 1.0.2 ou superior.

2. Preparar o projeto da primavera

Para implantar o aplicativo de API RESTful, a primeira etapa é preparar o projeto Spring para ser executado localmente.

Use as seguintes etapas para clonar e executar o aplicativo localmente:

1. Use o seguinte comando para clonar o projeto de exemplo do GitHub:

   git clone https://github.com/Azure-Samples/ASA-Samples-Restful-Application.git
   

2. Se você quiser executar o aplicativo localmente, conclua as etapas nas seções Expor APIs RESTful e Atualizar a configuração do aplicativo primeiro e, em seguida, use o seguinte comando para executar o aplicativo de exemplo com o Maven:

   cd ASA-Samples-Restful-Application
   ./mvnw spring-boot:run
   

3. Prepare o ambiente de nuvem

Os principais recursos necessários para executar este aplicativo de exemplo são uma instância do Azure Spring Apps e uma instância do Banco de Dados do Azure para PostgreSQL. As seções a seguir descrevem como criar esses recursos.

Portal do Azure + plug-in Maven

3.1. Inicie sessão no portal do Azure

Vá para o portal do Azure e insira suas credenciais para entrar no portal. A vista predefinida é o dashboard de serviço.

3.2. Criar uma instância do Azure Spring Apps

Use as seguintes etapas para criar uma instância de serviço do Azure Spring Apps:

1. Selecione Criar um recurso no canto do portal do Azure.

2. Selecione Compute>Azure Spring Apps.

3. Preencha o formulário Básico com as seguintes informações:

   Definição	Valor sugerido	Description
   Subscrição	O nome da subscrição.	A subscrição do Azure que quer utilizar para o servidor. Se tiver várias subscrições, escolha a subscrição na qual pretende ser cobrado pelo recurso.
   Grupo de recursos	myresourcegroup	Um nome de grupo de recursos novo ou um já existente na sua subscrição.
   Nome	Miasa	Um nome exclusivo que identifica seu serviço Azure Spring Apps. O nome deve ter entre 4 e 32 caracteres e pode conter apenas letras minúsculas, números e hífenes. O primeiro caractere do nome do serviço deve ser uma letra e o último caractere deve ser uma letra ou um número.
   Planear	Enterprise	O plano de preços que determina o recurso e o custo associados à sua instância.
   Região	A região mais próxima dos seus utilizadores.	A localização que esteja mais próxima dos seus utilizadores.
   Zona redundante	não selecionado	A opção para criar seu serviço Azure Spring Apps em uma zona de disponibilidade do Azure. Atualmente, esse recurso não é suportado em todas as regiões.
   Plano IP de software	Pay As You Go	O plano de preços que lhe permite pagar à medida que avança com as Aplicações Azure Spring.
   Termos	Selecionado	A caixa de seleção do contrato associada à oferta do Marketplace. É necessário selecionar essa caixa de seleção.
   Implantar projeto de exemplo	não selecionado	A opção para usar o aplicativo de exemplo interno.

4. Selecione Rever e Criar para rever as suas seleções. Em seguida, selecione Criar para provisionar a instância do Azure Spring Apps.

5. Na barra de ferramentas, selecione o ícone Notificações (um sino) para monitorizar o processo de implementação. Após a conclusão da implantação, você pode selecionar Fixar no painel, que cria um bloco para esse serviço no painel do portal do Azure como um atalho para a página Visão geral do serviço.

   

6. Selecione Ir para o recurso para ir para a página Visão Geral do Azure Spring Apps.

3.3. Preparar a instância do PostgreSQL

Use as seguintes etapas para criar um Banco de Dados do Azure para o servidor PostgreSQL:

1. Vá para o portal do Azure e selecione Criar um recurso.

2. Selecione Bases de Dados>Base de Dados do Azure para PostgreSQL.

3. Selecione a opção Implantação flexível do servidor .

   

4. Preencha a guia Noções básicas com as seguintes informações:

   • Nome do servidor: my-demo-pgsql
   • Região: East US
   • Versão do PostgreSQL: 14
   • Tipo de carga de trabalho: Desenvolvimento
   • Ativar alta disponibilidade: desselecionado
   • Método de autenticação: somente autenticação PostgreSQL
   • Nome de usuário do administrador: myadmin
   • Palavra-passe e Confirmar palavra-passe: Introduza uma palavra-passe.

5. Use as seguintes informações para configurar a guia Rede :

   • Método de conectividade: Acesso público (endereços IP permitidos)
   • Permitir acesso público de qualquer serviço do Azure no Azure a este servidor: selecionado

6. Selecione Rever + criar para rever as suas seleções e selecione Criar para provisionar o servidor. Esta operação pode demorar alguns minutos.

7. Aceda aos seu Servidor PostgreSQL no portal do Azure. Na página Visão geral, procure o valor Nome do servidor e registre-o para uso posterior. Você precisa dele para configurar as variáveis de ambiente para o aplicativo no Azure Spring Apps.

8. Selecione Bancos de dados no menu de navegação para criar um banco de dados - por exemplo, todo.

   

3.4. Conectar a instância do aplicativo à instância do PostgreSQL

Use as seguintes etapas para conectar suas instâncias de serviço:

1. Vá para sua instância do Azure Spring Apps no portal do Azure.

2. No menu de navegação, abra Aplicativos e selecione Criar aplicativo.

3. Na página Criar aplicativo, preencha o nome do aplicativo simple-todo-api e selecione artefatos Java como o tipo de implementação.

4. Selecione Criar para concluir a criação do aplicativo e, em seguida, selecione o aplicativo para exibir os detalhes.

5. Vá para o aplicativo que você criou no portal do Azure. Na página Visão geral, selecione Atribuir ponto de extremidade para expor o ponto de extremidade público do aplicativo. Salve a URL para acessar o aplicativo após a implantação.

6. Selecione Conector de Serviço no painel de navegação e, em seguida, selecione Criar para criar uma nova conexão de serviço.

   

7. Preencha a guia Noções básicas com as seguintes informações:

   • Tipo de serviço: DB para servidor flexível PostgreSQL
   • Nome da conexão: um nome gerado automaticamente é preenchido, que também pode ser modificado.
   • Subscrição: selecione a sua subscrição.
   • Servidor flexível PostgreSQL: my-demo-pgsql
   • Banco de dados PostgreSQL: Selecione o banco de dados que você criou.
   • Tipo de cliente: SpringBoot

   

8. Configure a guia Next: Authentication com as seguintes informações:

   Nota

   A Microsoft recomenda o uso do fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como para bancos de dados, caches, mensagens ou serviços de IA, requer um grau muito alto de confiança no aplicativo e traz riscos não presentes em outros fluxos. Use esse fluxo somente quando opções mais seguras, como identidades gerenciadas para conexões sem senha ou sem chave, não forem viáveis. Para operações de máquina local, prefira identidades de usuário para conexões sem senha ou sem chave.

   • Selecione o tipo de autenticação que você deseja usar entre o serviço de computação e o serviço de destino.: Selecione Cadeia de conexão.
   • Continuar com...: Selecione Credenciais do banco de dados
   • Nome de usuário: myadmin
   • Palavra-passe: Introduza a sua palavra-passe.

   

9. Selecione Next: Networking. Use a opção padrão Configurar regras de firewall para habilitar o acesso ao serviço de destino.

10. Selecione Seguinte: Rever e Criar para rever as suas seleções e, em seguida, selecione Criar para criar a ligação.

3.5. Expor APIs RESTful

Use as seguintes etapas para expor suas APIs RESTful no Microsoft Entra ID:

1. Inicie sessão no portal do Azure.

2. Se você tiver acesso a vários locatários, use o filtro Diretório + assinatura ( ) para selecionar o locatário no qual deseja registrar um aplicativo.

3. Procure e selecione Microsoft Entra ID.

4. Em Gerir, selecione Registos de>aplicações Novo registo.

5. Insira um nome para seu aplicativo no campo Nome - por exemplo, Todo. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.

6. Em Tipos de conta suportados, selecione Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra - Multilocatário) e contas pessoais da Microsoft.

7. Selecione Registar para criar a aplicação.

8. Na página Visão geral do aplicativo, procure o valor da ID do aplicativo (cliente) e registre-o para uso posterior. Você precisa dele para configurar o arquivo de configuração YAML para este projeto.

9. Em Gerenciar, selecione Expor uma API, localize o URI da ID do Aplicativo no início da página e selecione Adicionar.

10. Na página Editar URI da ID do aplicativo, aceite o URI da ID do Aplicativo proposto (api://{client ID}) ou use um nome significativo em vez da ID do cliente, como api://simple-todo, e selecione Salvar.

11. Em Gerenciar, selecione Expor uma API>Adicionar um escopo e insira as seguintes informações:

    • Em Nome do escopo, digite ToDo.Read.
    • Em Quem pode consentir, selecione Somente administradores.
    • Para Nome de exibição do Consentimento do administrador, insira Ler os dados do ToDo.
    • Para Descrição do consentimento do administrador, insira Permite que usuários autenticados leiam os dados do ToDo.
    • Para Estado, mantenha-o ativado.
    • Selecione Adicionar escopo.

12. Repita as etapas anteriores para adicionar os outros dois escopos: ToDo.Write e ToDo.Delete.

    

3.6. Atualizar a configuração do aplicativo

Use as seguintes etapas para atualizar o arquivo YAML para usar as informações do aplicativo registrado do Microsoft Entra para estabelecer um relacionamento com o aplicativo de API RESTful:

1. Localize o arquivo src/main/resources/application.yml para o simple-todo-api aplicativo. Atualize a spring.cloud.azure.active-directory configuração na seção para corresponder ao exemplo a seguir. Certifique-se de substituir os espaços reservados pelos valores criados anteriormente.

   spring:
     cloud:
       azure:
         active-directory:
           profile:
             tenant-id: <tenant>
           credential:
             client-id: <your-application-ID-of-ToDo>
           app-id-uri: <your-application-ID-URI-of-ToDo>
   

   Nota

   Nos tokens v1.0, a configuração requer o ID do cliente da API, enquanto nos tokens v2.0, você pode usar o ID do cliente ou o URI do ID do aplicativo na solicitação. Você pode configurar ambos para concluir corretamente a validação de audiência.

   Os valores permitidos são tenant-id : common, organizations, consumers, ou o ID do locatário. Para obter mais informações sobre esses valores, consulte a seção Usado o ponto de extremidade errado (contas pessoais e da organização) de AADSTS50020 de erro - A conta de usuário do provedor de identidade não existe no locatário. Para obter informações sobre como converter seu aplicativo de locatário único, consulte Converter aplicativo de locatário único em multilocatário no Microsoft Entra ID.

2. Use o seguinte comando para reconstruir o projeto de exemplo:

   ./mvnw clean package
   

CLI do Azure

3.1. Fornecer nomes para cada recurso

Crie variáveis para manter os nomes dos recursos usando os comandos a seguir. Certifique-se de substituir os espaços reservados pelos seus próprios valores.

Nota

A Microsoft recomenda o uso do fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como para bancos de dados, caches, mensagens ou serviços de IA, requer um grau muito alto de confiança no aplicativo e traz riscos não presentes em outros fluxos. Use esse fluxo somente quando opções mais seguras, como identidades gerenciadas para conexões sem senha ou sem chave, não forem viáveis. Para operações de máquina local, prefira identidades de usuário para conexões sem senha ou sem chave.

export RESOURCE_GROUP=myresourcegroup
export LOCATION=<location>
export POSTGRESQL_SERVER=my-demo-pgsql
export POSTGRESQL_DB=Todo
export POSTGRESQL_ADMIN_USERNAME=<admin-username>
export POSTGRESQL_ADMIN_PASSWORD=<admin-password>
export AZURE_SPRING_APPS_NAME=myasa
export APP_NAME=simple-todo-api
export TODO_APP_NAME=Todo
export TODO_APP_URL=api://simple-todo
export TODOWEB_APP_NAME=TodoWeb
export TODOWEB_APP_URL=api://simple-todoweb
export NEW_MEMBER_USERNAME=<new-member-username>
export NEW_MEMBER_PASSWORD=<new-member-password>
export USER_PRINCIPAL_NAME=<user-principal-name>

3.2. Criar um novo grupo de recursos

Use as seguintes etapas para criar um novo grupo de recursos:

1. Use o seguinte comando para entrar na CLI do Azure:

   az login
   

2. Use o seguinte comando para definir o local padrão:

   az configure --defaults location=${LOCATION}
   

3. Use o comando a seguir para listar todas as assinaturas disponíveis para determinar a ID da assinatura a ser usada:

   az account list --output table
   

4. Use o seguinte comando para definir a assinatura padrão:

   az account set --subscription <subscription-ID>
   

5. Use o seguinte comando para criar um grupo de recursos:

   az group create --resource-group ${RESOURCE_GROUP}
   

6. Use o seguinte comando para definir o grupo de recursos recém-criado como o grupo de recursos padrão:

   az configure --defaults group=${RESOURCE_GROUP}
   

3.3. Instalar extensão e registrar namespace

Use os seguintes comandos para instalar a extensão Azure Spring Apps para a CLI do Azure e registrar o Microsoft.SaaS namespace:

az extension add --name spring --upgrade
az provider register --namespace Microsoft.SaaS

3.4. Criar uma instância do Azure Spring Apps

Use as seguintes etapas para criar uma instância de serviço e um aplicativo na instância:

1. Use o seguinte comando para aceitar os termos legais e as declarações de privacidade do plano Enterprise:

   Nota

   Esta etapa é necessária somente se sua assinatura nunca tiver sido usada para criar uma instância do plano Enterprise do Azure Spring Apps.

   az term accept \
       --publisher vmware-inc \
       --product azure-spring-cloud-vmware-tanzu-2 \
       --plan asa-ent-hr-mtr
   

2. Use o seguinte comando para criar uma instância de serviço do Azure Spring Apps:

   az spring create --name ${AZURE_SPRING_APPS_NAME} --sku enterprise
   

3. Use o seguinte comando para criar um aplicativo na instância do Azure Spring Apps:

   az spring app create \
       --service ${AZURE_SPRING_APPS_NAME} \
       --name ${APP_NAME} \
       --assign-endpoint true
   

3.5. Preparar a instância do PostgreSQL

O aplicativo Web Spring usa H2 para o banco de dados em localhost e o Banco de Dados do Azure para PostgreSQL para o banco de dados no Azure.

Use o seguinte comando para criar uma instância do PostgreSQL:

Nota

A Microsoft recomenda o uso do fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como para bancos de dados, caches, mensagens ou serviços de IA, requer um grau muito alto de confiança no aplicativo e traz riscos não presentes em outros fluxos. Use esse fluxo somente quando opções mais seguras, como identidades gerenciadas para conexões sem senha ou sem chave, não forem viáveis. Para operações de máquina local, prefira identidades de usuário para conexões sem senha ou sem chave.

az postgres flexible-server create \
    --name ${POSTGRESQL_SERVER} \
    --database-name ${POSTGRESQL_DB} \
    --admin-user ${POSTGRESQL_ADMIN_USERNAME} \
    --admin-password ${POSTGRESQL_ADMIN_PASSWORD} \
    --public-access 0.0.0.0

A especificação 0.0.0.0 habilita o acesso público de quaisquer recursos implantados no Azure para acessar seu servidor.

3.6. Conectar a instância do aplicativo à instância do PostgreSQL

Depois que a instância do aplicativo e a instância do PostgreSQL são criadas, a instância do aplicativo não pode acessar a instância do PostgreSQL diretamente. Use as seguintes etapas para permitir que o aplicativo se conecte à instância do PostgreSQL:

1. Use o seguinte comando para obter o nome de domínio totalmente qualificado da instância do PostgreSQL:

   export PSQL_FQDN=$(az postgres flexible-server show \
       --name ${POSTGRESQL_SERVER} \
       --query fullyQualifiedDomainName \
       --output tsv)
   

2. Use o seguinte comando para fornecer as spring.datasource. propriedades ao aplicativo por meio de variáveis de ambiente:

   Nota

   A Microsoft recomenda o uso do fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como para bancos de dados, caches, mensagens ou serviços de IA, requer um grau muito alto de confiança no aplicativo e traz riscos não presentes em outros fluxos. Use esse fluxo somente quando opções mais seguras, como identidades gerenciadas para conexões sem senha ou sem chave, não forem viáveis. Para operações de máquina local, prefira identidades de usuário para conexões sem senha ou sem chave.

   az spring app update \
       --service ${AZURE_SPRING_APPS_NAME} \
       --name ${APP_NAME} \
       --env SPRING_DATASOURCE_URL="jdbc:postgresql://${PSQL_FQDN}:5432/${POSTGRESQL_DB}?sslmode=require" \
             SPRING_DATASOURCE_USERNAME="${POSTGRESQL_ADMIN_USERNAME}" \
             SPRING_DATASOURCE_PASSWORD="${POSTGRESQL_ADMIN_PASSWORD}"
   

3.7. Expor APIs RESTful

Use as seguintes etapas para expor as APIs RESTful:

1. Use o seguinte comando para criar um aplicativo Microsoft Entra ID:

   az ad app create \
       --display-name ${TODO_APP_NAME} \
       --sign-in-audience AzureADandPersonalMicrosoftAccount \
       --identifier-uris ${TODO_APP_URL}
   

2. Use o seguinte comando para criar uma entidade de serviço para o aplicativo:

   az ad sp create --id ${TODO_APP_URL}
   

3. Use o seguinte comando para gerar IDs de permissão:

   permissionid1=$(uuidgen);permissionid2=$(uuidgen);permissionid3=$(uuidgen)
   

4. Adicione os seguintes escopos como JSON:

   api=$(echo '{
    "oauth2PermissionScopes": [
        {
            "adminConsentDescription": "Allows authenticated users to delete the ToDo data",
            "adminConsentDisplayName": "Delete the ToDo data",
            "id": "'$permissionid1'",
            "isEnabled": true,
            "type": "Admin",
            "userConsentDescription": null,
            "userConsentDisplayName": null,
            "value": "ToDo.Delete"
        },
   
        {
            "adminConsentDescription": "Allows authenticated users to write the ToDo data",
            "adminConsentDisplayName": "Write the ToDo data",
            "id": "'$permissionid2'",
            "isEnabled": true,
            "type": "Admin",
            "userConsentDescription": null,
            "userConsentDisplayName": null,
            "value": "ToDo.Write"
        },
        {
            "adminConsentDescription": "Allows authenticated users to read the ToDo data",
            "adminConsentDisplayName": "Read the ToDo data",
            "id": "'$permissionid3'",
            "isEnabled": true,
            "type": "Admin",
            "userConsentDescription": null,
            "userConsentDisplayName": null,
            "value": "ToDo.Read"
        }
    ]}')
   

5. Use o seguinte comando para adicionar escopos:

   az ad app update \
       --id ${TODO_APP_URL} \
       --set api="$api"
   

6. Use o seguinte comando para obter a ID do locatário a ser usada na próxima etapa:

   az account show --query "tenantId" --output tsv
   

7. Use o seguinte comando para obter a ID do aplicativo a ser usada nas próximas etapas:

   appid=$(az ad app show \
       --id ${TODO_APP_URL} \
       --query appId \
       --output tsv);
   echo $appid
   

3.8. Atualizar a configuração do aplicativo

Use as seguintes etapas para atualizar o arquivo YAML para usar as informações do aplicativo registrado do Microsoft Entra para estabelecer um relacionamento com o aplicativo de API RESTful:

1. Localize o arquivo src/main/resources/application.yml para o simple-todo-api aplicativo. Atualize a spring.cloud.azure.active-directory configuração na seção para corresponder ao exemplo a seguir. Certifique-se de substituir os espaços reservados pelos valores criados anteriormente.

   spring:
     cloud:
       azure:
         active-directory:
           profile:
             tenant-id: <tenant>
           credential:
             client-id: <your-application-ID-of-ToDo>
           app-id-uri: <your-application-ID-URI-of-ToDo>
   

   Nota

   Nos tokens v1.0, a configuração requer o ID do cliente da API, enquanto nos tokens v2.0, você pode usar o ID do cliente ou o URI do ID do aplicativo na solicitação. Você pode configurar ambos para concluir corretamente a validação de audiência.

   Os valores permitidos são tenant-id : common, organizations, consumers, ou o ID do locatário. Para obter mais informações sobre esses valores, consulte a seção Usado o ponto de extremidade errado (contas pessoais e da organização) de AADSTS50020 de erro - A conta de usuário do provedor de identidade não existe no locatário. Para obter informações sobre como converter seu aplicativo de locatário único, consulte Converter aplicativo de locatário único em multilocatário no Microsoft Entra ID.

2. Use o seguinte comando para reconstruir o projeto de exemplo:

   ./mvnw clean package
   

4. Implantar o aplicativo no Azure Spring Apps

Portal do Azure + plug-in Maven

Agora você pode implantar o aplicativo no Azure Spring Apps.

Use as seguintes etapas para implantar usando o plug-in Maven para Azure Spring Apps:

1. Navegue até o diretório completo e execute o seguinte comando para configurar o aplicativo no Azure Spring Apps:

   ./mvnw com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config
   

   A lista a seguir descreve as interações de comando:

   • Login OAuth2: você precisa autorizar o logon no Azure com base no protocolo OAuth2.
   • Selecionar assinatura: selecione o número da lista de assinaturas da instância do Azure Spring Apps que você criou, que assume como padrão a primeira assinatura na lista. Se você usar o número padrão, pressione Enter diretamente.
   • Usar aplicativos Azure Spring existentes no Azure: pressione y para usar a instância existente do Azure Spring Apps.
   • Selecione Azure Spring Apps para implantação: selecione o número da instância do Azure Spring Apps que você criou. Se você usar o número padrão, pressione Enter diretamente.
   • Usar aplicativo existente no Azure Spring Apps <your-instance-name>: pressione y para usar o aplicativo criado.
   • Confirme para salvar todas as configurações acima: Pressione y. Se você pressionar n, a configuração não será salva nos arquivos POM.

2. Use o seguinte comando para implantar o aplicativo:

   ./mvnw azure-spring-apps:deploy
   

   A lista a seguir descreve a interação de comando:

   • Login OAuth2: você precisa autorizar o logon no Azure com base no protocolo OAuth2.

   Depois que o comando for executado, você poderá ver nas seguintes mensagens de log que a implantação foi bem-sucedida:

[INFO] Deployment Status: Running
[INFO]   InstanceName:simple-todo-api-default-15-xxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:N/A       
[INFO] Getting public url of app(simple-todo-api)...
[INFO] Application url: https://<your-Azure-Spring-Apps-instance-name>-simple-todo-api.azuremicroservices.io

CLI do Azure

Use o seguinte comando para implantar o aplicativo com base no código-fonte:

az spring app deploy \
    --service ${AZURE_SPRING_APPS_NAME} \
    --name ${APP_NAME} \
    --build-env BP_JVM_VERSION=17 \
    --source-path .

5. Valide o aplicativo

Portal do Azure + plug-in Maven

Agora você pode acessar a API RESTful para ver se ela funciona.

5.1. Pedir um token de acesso

As APIs RESTful atuam como um servidor de recursos, que é protegido pelo Microsoft Entra ID. Antes de adquirir um token de acesso, você deve registrar outro aplicativo no Microsoft Entra ID e conceder permissões ao aplicativo cliente, que é chamado ToDoWeb.

Registar a aplicação cliente

Use as seguintes etapas para registrar um aplicativo no Microsoft Entra ID, que é usado para adicionar as permissões para o ToDo aplicativo:

1. Inicie sessão no portal do Azure.

2. Se você tiver acesso a vários locatários, use o filtro Diretório + assinatura ( ) para selecionar o locatário no qual deseja registrar um aplicativo.

3. Procure e selecione Microsoft Entra ID.

4. Em Gerir, selecione Registos de>aplicações Novo registo.

5. Insira um nome para seu aplicativo no campo Nome - por exemplo, ToDoWeb. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.

6. Para Tipos de conta suportados, use o valor padrão Contas somente neste diretório organizacional.

7. Selecione Registar para criar a aplicação.

8. Na página Visão geral do aplicativo, procure o valor da ID do aplicativo (cliente) e registre-o para uso posterior. Você precisa dele para adquirir um token de acesso.

9. Selecione Permissões>de API Adicionar uma permissão>Minhas APIs. Selecione o ToDo aplicativo que você registrou anteriormente e, em seguida, selecione as permissões ToDo.Read, ToDo.Write e ToDo.Delete. Selecione Adicionar permissões.

10. Selecione Conceder consentimento de administrador para <seu nome> de locatário para conceder consentimento de administrador para as permissões adicionadas.

    

Adicionar usuário para acessar as APIs RESTful

Use as etapas a seguir para criar um usuário membro em seu locatário do Microsoft Entra. Em seguida, o usuário pode gerenciar os ToDo dados do aplicativo por meio de APIs RESTful.

1. Em Gerenciar, selecione Usuários>Novo usuário>Criar novo usuário.

2. Na página Criar novo usuário, insira as seguintes informações:

   • Nome principal do usuário: insira um nome para o usuário.
   • Nome para exibição: insira um nome para exibição para o usuário.
   • Senha: copie a senha gerada automaticamente fornecida na caixa Senha .

   Nota

   Novos usuários devem concluir a primeira autenticação de entrada e atualizar suas senhas, caso contrário, você receberá um AADSTS50055: The password is expired erro quando receber o token de acesso.

   Quando um novo usuário faz login, ele recebe um prompt de Ação necessária . Eles podem escolher Perguntar mais tarde para ignorar a validação.

3. Selecione Rever + criar para rever as suas seleções. Selecione Criar para criar o usuário.

Atualizar a configuração OAuth2 para autorização da interface do usuário do Swagger

Use as etapas a seguir para atualizar a configuração OAuth2 para autorização da interface do usuário do Swagger. Em seguida, você pode autorizar os usuários a adquirir tokens de acesso por meio do ToDoWeb aplicativo.

1. Abra seu locatário do Microsoft Entra ID no portal do Azure e vá para o aplicativo registrado ToDoWeb .

2. Em Gerir, selecione Autenticação, selecione Adicionar uma plataforma e, em seguida, selecione Aplicação de página única.

3. Use o formato <your-app-exposed-application-URL-or-endpoint>/swagger-ui/oauth2-redirect.html como a URL de redirecionamento OAuth2 no campo URIs de redirecionamento e selecione Configurar.

   

CLI do Azure

Agora você pode acessar a API RESTful para ver se ela funciona.

5.1. Pedir um token de acesso

As APIs RESTful atuam como um servidor de recursos, que é protegido pelo Microsoft Entra ID. Antes de adquirir um token de acesso, é necessário registrar outro aplicativo no Microsoft Entra ID e conceder permissões ao aplicativo cliente, chamado ToDoWeb.

Registar a aplicação cliente

Use as seguintes etapas para registrar o aplicativo cliente:

1. Use o seguinte comando para criar um aplicativo Microsoft Entra ID, que é usado para adicionar as permissões para o ToDo aplicativo:

   az ad app create \
       --display-name ${TODOWEB_APP_NAME} \
       --sign-in-audience AzureADMyOrg \
       --identifier-uris ${TODOWEB_APP_URL}
   

2. Use o seguinte comando para adicionar permissões:

   az ad app permission add \
       --id api://simple-todowebtest2 \
       --api $appid \
       --api-permissions $permissionid1=Scope $permissionid2=Scope $permissionid3=Scope
   

3. Use o seguinte comando para conceder consentimento de administrador para as permissões adicionadas:

   az ad app permission admin-consent --id ${TODOWEB_APP_URL}
   

4. Use o seguinte comando para obter a ID do cliente do ToDoWeb aplicativo usado na etapa Obter o token de acesso:

   az ad app show \
       --id ${TODOWEB_APP_URL} \
       --query appId \
       --output tsv
   

Adicionar usuário para acessar as APIs RESTful

Use o comando a seguir para criar um usuário membro em seu locatário do Microsoft Entra. Em seguida, o usuário pode gerenciar os ToDo dados do aplicativo por meio de APIs RESTful:

Nota

A Microsoft recomenda o uso do fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como para bancos de dados, caches, mensagens ou serviços de IA, requer um grau muito alto de confiança no aplicativo e traz riscos não presentes em outros fluxos. Use esse fluxo somente quando opções mais seguras, como identidades gerenciadas para conexões sem senha ou sem chave, não forem viáveis. Para operações de máquina local, prefira identidades de usuário para conexões sem senha ou sem chave.

az ad user create \
    --display-name ${NEW_MEMBER_USERNAME} \
    --password ${NEW_MEMBER_PASSWORD} \
    --user-principal-name ${USER_PRINCIPAL_NAME}

Atualizar a configuração OAuth2 para autorização da interface do usuário do Swagger

Use as seguintes etapas para atualizar a configuração do OAuth2:

1. Use o seguinte comando para obter a ID do objeto do ToDoWeb aplicativo:

   az ad app show --id ${TODOWEB_APP_URL} --query id
   

2. Use o seguinte comando para obter a URL do seu simple-todo-api aplicativo:

   az spring app show \
       --name ${APP_NAME} \
       --service ${AZURE_SPRING_APPS_NAME} \
       --query properties.url
   

3. Use o comando a seguir para atualizar a configuração OAuth2 para autorização da interface do usuário do Swagger, substituindo os <object-id> espaços reservados e <URL> pelos valores de parâmetro obtidos. Em seguida, você pode autorizar os usuários a adquirir tokens de acesso por meio do ToDoWeb aplicativo.

   az rest \
       --method PATCH \
       --uri "https://graph.microsoft.com/v1.0/applications/<object-id>" \
       --headers 'Content-Type=application/json' \
       --body '{"spa":{"redirectUris":["<URL>/swagger-ui/oauth2-redirect.html"]}}'
   

2. Preparar o projeto da primavera

Para implantar o aplicativo de API RESTful, a primeira etapa é preparar o projeto Spring para ser executado localmente.

Portal do Azure + plug-in Maven

Use as seguintes etapas para clonar e executar o aplicativo localmente:

1. Use o seguinte comando para clonar o projeto de exemplo do GitHub:

   git clone https://github.com/Azure-Samples/ASA-Samples-Restful-Application.git
   

2. Se você quiser executar o aplicativo localmente, conclua as etapas nas seções Expor APIs RESTful e Atualizar a configuração do aplicativo primeiro e, em seguida, use o seguinte comando para executar o aplicativo de exemplo com o Maven:

   cd ASA-Samples-Restful-Application
   ./mvnw spring-boot:run
   

CLI do desenvolvedor do Azure

Use as seguintes etapas para inicializar o aplicativo Web a partir dos modelos da CLI do Desenvolvedor do Azure:

1. Abra um terminal, crie uma nova pasta vazia e altere o diretório para ela.

2. Execute o seguinte comando para inicializar o projeto:

   azd init --template Azure-Samples/ASA-Samples-Restful-Application
   

   A lista a seguir descreve as interações de comando:

   • Login OAuth2: você precisa autorizar o logon no Azure com base no protocolo OAuth2.
   • Insira um novo nome de ambiente: Forneça um nome de ambiente. Esse nome é usado como um sufixo para o grupo de recursos criado para armazenar todos os recursos do Azure. Esse nome deve ser exclusivo em sua assinatura do Azure.

   O console emite mensagens semelhantes ao exemplo a seguir:

   Initializing a new project (azd init)
   
   Downloading template code to: <your-local-path>
   (✓) Done: Initialized git repository
   
   Enter a new environment name: <your-env-name>
   
   SUCCESS: New project initialized!
   You can view the template code in your directory: <your-local-path>
   Learn more about running 3rd party code on our DevHub: https://aka.ms/azd-third-party-code-notice
   

3. Prepare o ambiente de nuvem

Os principais recursos necessários para executar este aplicativo de exemplo são uma instância do Azure Spring Apps e uma instância do Banco de Dados do Azure para PostgreSQL. As seções a seguir descrevem como criar esses recursos.

Portal do Azure + plug-in Maven

3.1. Inicie sessão no portal do Azure

Vá para o portal do Azure e insira suas credenciais para entrar no portal. A vista predefinida é o dashboard de serviço.

3.2. Criar uma instância do Azure Spring Apps

Use as seguintes etapas para criar uma instância de serviço:

1. Selecione Criar um recurso no canto do portal.

2. Selecione Compute>Azure Spring Apps.

3. Preencha o formulário Noções básicas . Use a tabela a seguir como um guia para preencher o formulário. O valor recomendado do Plano é Consumo padrão e dedicado (visualização).

   Definição	Valor sugerido	Description
   Subscrição	O nome da subscrição.	A subscrição do Azure que quer utilizar para o servidor. Se tiver várias subscrições, escolha a subscrição na qual pretende ser cobrado pelo recurso.
   Grupo de recursos	myresourcegroup	Um nome de grupo de recursos novo ou um já existente na sua subscrição.
   Nome	Miasa	Um nome exclusivo que identifica seu serviço Azure Spring Apps. O nome deve ter entre 4 e 32 caracteres e pode conter apenas letras minúsculas, números e hífenes. O primeiro caractere do nome do serviço deve ser uma letra e o último caractere deve ser uma letra ou um número.
   Planear	Consumo padrão e dedicado (pré-visualização)	O plano de preços determina os recursos e o custo associados à sua instância.
   Região	A região mais próxima dos seus utilizadores.	A localização que esteja mais próxima dos seus utilizadores.
   Ambiente de aplicativos de contêiner	myenvironment	A opção para selecionar qual instância do ambiente Container Apps compartilhar a mesma rede virtual com outros serviços e recursos.

   Use a tabela a seguir como um guia para a criação do Ambiente de Aplicativos de Contêiner:

   Definição	Valor sugerido	Description
   Nome do ambiente	myenvironment	Um nome exclusivo que identifica seu serviço de Ambiente de Aplicativos de Contêiner do Azure.
   Planear	Consumo	O plano de preços determina os recursos e o custo associados à sua instância.
   Zona redundante	Desativado	A opção para criar o serviço Ambiente de Aplicativos de Contêiner em uma zona de disponibilidade do Azure.

4. Selecione Rever e Criar para rever as suas seleções. Em seguida, selecione Criar para provisionar a instância do Azure Spring Apps.

5. Na barra de ferramentas, selecione o ícone Notificações (um sino) para monitorizar o processo de implementação. Após a conclusão da implantação, você pode selecionar Fixar no painel, que cria um bloco para esse serviço no painel do portal do Azure como um atalho para a página Visão geral do serviço.

6. Selecione Ir para recurso para abrir a página Visão geral do serviço.

   

Importante

O perfil de carga de trabalho de Consumo tem um modelo de faturamento pré-pago, sem custo inicial. Você é cobrado pelo perfil de carga de trabalho dedicada com base nos recursos provisionados. Para obter mais informações, consulte Perfis de carga de trabalho nos preços dos Aplicativos de Contêiner do Azure e dos Aplicativos Azure Spring.

3.3. Preparar a instância do PostgreSQL

Use as seguintes etapas para criar um Banco de Dados do Azure para o servidor PostgreSQL:

1. Vá para o portal do Azure e selecione Criar um recurso.

2. Selecione Bases de Dados>Base de Dados do Azure para PostgreSQL.

3. Selecione a opção Implantação flexível do servidor .

   

4. Preencha a guia Noções básicas com as seguintes informações:

   • Nome do servidor: my-demo-pgsql
   • Região: East US
   • Versão do PostgreSQL: 14
   • Tipo de carga de trabalho: Desenvolvimento
   • Ativar alta disponibilidade: desselecionado
   • Método de autenticação: somente autenticação PostgreSQL
   • Nome de usuário do administrador: myadmin
   • Palavra-passe e Confirmar palavra-passe: Introduza uma palavra-passe.

5. Use as seguintes informações para configurar a guia Rede :

   • Método de conectividade: Acesso público (endereços IP permitidos)
   • Permitir acesso público de qualquer serviço do Azure no Azure a este servidor: selecionado

6. Selecione Rever + criar para rever as suas seleções e selecione Criar para provisionar o servidor. Esta operação pode demorar alguns minutos.

7. Aceda aos seu Servidor PostgreSQL no portal do Azure. Na página Visão geral, procure o valor Nome do servidor e registre-o para uso posterior. Você precisa dele para configurar as variáveis de ambiente para o aplicativo no Azure Spring Apps.

8. Selecione Bancos de dados no menu de navegação para criar um banco de dados - por exemplo, todo.

   

3.4. Conectar a instância do aplicativo à instância do PostgreSQL

Use as seguintes etapas para conectar suas instâncias de serviço:

1. Vá para sua instância do Azure Spring Apps no portal do Azure.

2. No menu de navegação, abra Aplicativos e selecione Criar aplicativo.

3. Na página Criar aplicativo, preencha o nome do aplicativo simple-todo-api e selecione artefatos Java como o tipo de implementação.

4. Selecione Criar para concluir a criação do aplicativo e selecione o aplicativo para exibir os detalhes.

5. Vá para o aplicativo que você criou no portal do Azure. Na página Visão geral, selecione Atribuir ponto de extremidade para expor o ponto de extremidade público do aplicativo. Salve a URL para acessar o aplicativo após a implantação.

6. Vá para o aplicativo que você criou, expanda Configurações e selecione Configuração no menu de navegação e, em seguida, selecione Variáveis de ambiente para definir as variáveis de ambiente.

7. Adicione as seguintes variáveis de ambiente para a conexão PostgreSQL e selecione Salvar para concluir a atualização de configuração do aplicativo. Certifique-se de substituir os espaços reservados por seus próprios valores que você criou anteriormente.

   Variável de ambiente	Value
   SPRING_DATASOURCE_URL	jdbc:postgresql://<your-PostgreSQL-server-name>:5432/<your-PostgreSQL-database-name>
   SPRING_DATASOURCE_USERNAME	<your-PostgreSQL-admin-user>
   SPRING_DATASOURCE_PASSWORD	<your-PostgreSQL-admin-password>

   

3.5. Expor APIs RESTful

Use as seguintes etapas para expor suas APIs RESTful no Microsoft Entra ID:

1. Inicie sessão no portal do Azure.

2. Se você tiver acesso a vários locatários, use o filtro Diretório + assinatura ( ) para selecionar o locatário no qual deseja registrar um aplicativo.

3. Procure e selecione Microsoft Entra ID.

4. Em Gerir, selecione Registos de>aplicações Novo registo.

5. Insira um nome para seu aplicativo no campo Nome - por exemplo, Todo. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.

6. Em Tipos de conta suportados, selecione Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra - Multilocatário) e contas pessoais da Microsoft.

7. Selecione Registar para criar a aplicação.

8. Na página Visão geral do aplicativo, procure o valor da ID do aplicativo (cliente) e registre-o para uso posterior. Você precisa dele para configurar o arquivo de configuração YAML para este projeto.

9. Em Gerenciar, selecione Expor uma API, localize o URI da ID do Aplicativo no início da página e selecione Adicionar.

10. Na página Editar URI da ID do aplicativo, aceite o URI da ID do Aplicativo proposto (api://{client ID}) ou use um nome significativo em vez da ID do cliente, como api://simple-todo, e selecione Salvar.

11. Em Gerenciar, selecione Expor uma API>Adicionar um escopo e insira as seguintes informações:

    • Em Nome do escopo, digite ToDo.Read.
    • Em Quem pode consentir, selecione Somente administradores.
    • Para Nome de exibição do Consentimento do administrador, insira Ler os dados do ToDo.
    • Para Descrição do consentimento do administrador, insira Permite que usuários autenticados leiam os dados do ToDo.
    • Para Estado, mantenha-o ativado.
    • Selecione Adicionar escopo.

12. Repita as etapas anteriores para adicionar os outros dois escopos: ToDo.Write e ToDo.Delete.

    

3.6. Atualizar a configuração do aplicativo

Use as seguintes etapas para atualizar o arquivo YAML para usar as informações do aplicativo registrado do Microsoft Entra para estabelecer um relacionamento com o aplicativo de API RESTful:

1. Localize o arquivo src/main/resources/application.yml para o simple-todo-api aplicativo. Atualize a spring.cloud.azure.active-directory configuração na seção para corresponder ao exemplo a seguir. Certifique-se de substituir os espaços reservados pelos valores criados anteriormente.

   spring:
     cloud:
       azure:
         active-directory:
           profile:
             tenant-id: <tenant>
           credential:
             client-id: <your-application-ID-of-ToDo>
           app-id-uri: <your-application-ID-URI-of-ToDo>
   

   Nota

   Nos tokens v1.0, a configuração requer o ID do cliente da API, enquanto nos tokens v2.0, você pode usar o ID do cliente ou o URI do ID do aplicativo na solicitação. Você pode configurar ambos para concluir corretamente a validação de audiência.

   Os valores permitidos são tenant-id : common, organizations, consumers, ou o ID do locatário. Para obter mais informações sobre esses valores, consulte a seção Usado o ponto de extremidade errado (contas pessoais e da organização) de AADSTS50020 de erro - A conta de usuário do provedor de identidade não existe no locatário. Para obter informações sobre como converter seu aplicativo de locatário único, consulte Converter aplicativo de locatário único em multilocatário no Microsoft Entra ID.

2. Use o seguinte comando para reconstruir o projeto de exemplo:

   ./mvnw clean package
   

CLI do desenvolvedor do Azure

3.1. Preparar os recursos do Azure

Use as seguintes etapas para provisionar os recursos necessários do Azure:

1. Execute o seguinte comando para iniciar sessão no Azure com OAuth2. Ignore este passo se já tiver iniciado sessão.

   azd auth login
   

2. Execute o seguinte comando para habilitar o recurso Azure Spring Apps:

   azd config set alpha.springapp on
   

3. Execute o seguinte comando para empacotar uma cópia implantável do seu aplicativo, provisionar a infraestrutura do modelo no Azure e implantar o código do aplicativo nesses recursos recém-provisionados:

   azd provision
   

   A lista a seguir descreve as interações de comando:

   • Selecione uma Assinatura do Azure para usar: use as setas para mover, digite para filtrar e pressione Enter.
   • Selecione um local do Azure para usar: use as setas para mover, digite para filtrar e pressione Enter.

   O console emite mensagens semelhantes ao exemplo a seguir:

   SUCCESS: Your application was provisioned in Azure in xx minutes xx seconds.
   You can view the resources created under the resource group rg-<your-environment-name>> in Azure Portal:
   https://portal.azure.com/#@/resource/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/overview
   

   Nota

   Esse comando pode demorar um pouco para ser concluído. Você vê um indicador de progresso à medida que provisiona recursos do Azure.

3.2. Expor APIs RESTful

Use as seguintes etapas para expor suas APIs RESTful no Microsoft Entra ID:

1. Inicie sessão no portal do Azure.

2. Se você tiver acesso a vários locatários, use o filtro Diretório + assinatura ( ) para selecionar o locatário no qual deseja registrar um aplicativo.

3. Procure e selecione Microsoft Entra ID.

4. Em Gerir, selecione Registos de>aplicações Novo registo.

5. Insira um nome para seu aplicativo no campo Nome - por exemplo, Todo. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.

6. Em Tipos de conta suportados, selecione Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra - Multilocatário) e contas pessoais da Microsoft.

7. Selecione Registar para criar a aplicação.

8. Na página Visão geral do aplicativo, procure o valor da ID do aplicativo (cliente) e registre-o para uso posterior. Você precisa dele para configurar o arquivo de configuração YAML para este projeto.

9. Em Gerenciar, selecione Expor uma API, localize o URI da ID do Aplicativo no início da página e selecione Adicionar.

10. Na página Editar URI da ID do aplicativo, aceite o URI da ID do Aplicativo proposto (api://{client ID}) ou use um nome significativo em vez da ID do cliente, como api://simple-todo, e selecione Salvar.

11. Em Gerenciar, selecione Expor uma API>Adicionar um escopo e insira as seguintes informações:

    • Em Nome do escopo, digite ToDo.Read.
    • Em Quem pode consentir, selecione Somente administradores.
    • Para Nome de exibição do Consentimento do administrador, insira Ler os dados do ToDo.
    • Para Descrição do consentimento do administrador, insira Permite que usuários autenticados leiam os dados do ToDo.
    • Para Estado, mantenha-o ativado.
    • Selecione Adicionar escopo.

12. Repita as etapas anteriores para adicionar os outros dois escopos: ToDo.Write e ToDo.Delete.

    

3.3. Atualizar a configuração do aplicativo

Use as seguintes etapas para atualizar o arquivo YAML para usar as informações do aplicativo registrado do Microsoft Entra para estabelecer um relacionamento com o aplicativo de API RESTful:

1. Localize o arquivo src/main/resources/application.yml para o simple-todo-api aplicativo. Atualize a spring.cloud.azure.active-directory configuração na seção para corresponder ao exemplo a seguir. Certifique-se de substituir os espaços reservados pelos valores criados anteriormente.

   spring:
     cloud:
       azure:
         active-directory:
           profile:
             tenant-id: <tenant>
           credential:
             client-id: <your-application-ID-of-ToDo>
           app-id-uri: <your-application-ID-URI-of-ToDo>
   

   Nota

   Nos tokens v1.0, a configuração requer o ID do cliente da API, enquanto nos tokens v2.0, você pode usar o ID do cliente ou o URI do ID do aplicativo na solicitação. Você pode configurar ambos para concluir corretamente a validação de audiência.

   Os valores permitidos são tenant-id : common, organizations, consumers, ou o ID do locatário. Para obter mais informações sobre esses valores, consulte a seção Usado o ponto de extremidade errado (contas pessoais e da organização) de AADSTS50020 de erro - A conta de usuário do provedor de identidade não existe no locatário. Para obter informações sobre como converter seu aplicativo de locatário único, consulte Converter aplicativo de locatário único em multilocatário no Microsoft Entra ID.

2. Use o seguinte comando para reconstruir o projeto de exemplo:

   ./mvnw clean package
   

4. Implantar o aplicativo no Azure Spring Apps

Agora você pode implantar o aplicativo no Azure Spring Apps.

Portal do Azure + plug-in Maven

Use as seguintes etapas para implantar usando o plug-in Maven para Azure Spring Apps:

1. Navegue até o diretório completo e execute o seguinte comando para configurar o aplicativo no Azure Spring Apps:

   ./mvnw com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config
   

   A lista a seguir descreve as interações de comando:

   • Login OAuth2: você precisa autorizar o logon no Azure com base no protocolo OAuth2.
   • Selecionar assinatura: selecione o número da lista de assinaturas da instância do Azure Spring Apps que você criou, que assume como padrão a primeira assinatura na lista. Se você usar o número padrão, pressione Enter diretamente.
   • Usar aplicativos Azure Spring existentes no Azure: pressione y para usar a instância existente do Azure Spring Apps.
   • Selecione Azure Spring Apps para implantação: selecione o número da instância do Azure Spring Apps que você criou. Se você usar o número padrão, pressione Enter diretamente.
   • Usar aplicativo existente no Azure Spring Apps <your-instance-name>: pressione y para usar o aplicativo criado.
   • Confirme para salvar todas as configurações acima: Pressione y. Se você pressionar n, a configuração não será salva nos arquivos POM.

2. Use o seguinte comando para implantar o aplicativo:

   ./mvnw azure-spring-apps:deploy
   

   A lista a seguir descreve a interação de comando:

   • Login OAuth2: você precisa autorizar o logon no Azure com base no protocolo OAuth2.

   Depois que o comando for executado, você poderá ver nas seguintes mensagens de log que a implantação foi bem-sucedida:

[INFO] Deployment(default) is successfully created
[INFO] Starting Spring App after deploying artifacts...
[INFO] Deployment Status: Running
[INFO]   InstanceName:demo--default-xxxxxxx-xxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:NONE
[INFO] Getting public url of app(demo)...
[INFO] Application url: https://demo.<unique-identifier>.<region-name>.azurecontainerapps.io

CLI do desenvolvedor do Azure

Use as etapas a seguir para empacotar o aplicativo, provisionar os recursos do Azure exigidos pelo aplicativo Web e implantar no Azure Spring Apps.

1. Execute o seguinte comando para empacotar uma cópia implantável do seu aplicativo:

   azd package
   

2. Execute o seguinte comando para implantar o código do aplicativo nesses recursos recém-provisionados:

   azd deploy
   

   O console emite mensagens semelhantes ao exemplo a seguir:

   Deploying services (azd deploy)
   
   WARNING: Feature 'springapp' is in alpha stage.
   To learn more about alpha features and their support, visit https://aka.ms/azd-feature-stages.
   
   ...
   
   Deploying service simple-todo-api (Fetching endpoints for spring app service)
   - Endpoint: https://simple-todo-api.xxxxxxxx-xxxxxxxx.xxxxxx.azurecontainerapps.io
   
   
   SUCCESS: Your application was deployed to Azure in xx minutes xx seconds.
   You can view the resources created under the resource group rg-<your-environment-name> in Azure Portal:
   https://portal.azure.com/#@/resource/subscriptions/<your-subscription-id>/resourceGroups/rg-<your-environment-name>/overview
   

   O Endpoint de saída é o ponto de extremidade base para acessar o aplicativo ToDo API.

Nota

Você também pode usar azd up para combinar os três comandos anteriores: azd provision (provisiona recursos do Azure), azd package (empacota uma cópia implantável do seu aplicativo) e (implanta azd deploy o código do aplicativo). Para obter mais informações, consulte Azure-Samples/ASA-Samples-Restful-Application.

5. Valide o aplicativo

Agora você pode acessar a API RESTful para ver se ela funciona.

5.1. Pedir um token de acesso

As APIs RESTful atuam como um servidor de recursos, que é protegido pelo Microsoft Entra ID. Antes de adquirir um token de acesso, você deve registrar outro aplicativo no Microsoft Entra ID e conceder permissões ao aplicativo cliente, que é chamado ToDoWeb.

Registar a aplicação cliente

Use as seguintes etapas para registrar um aplicativo no Microsoft Entra ID, que é usado para adicionar as permissões para o ToDo aplicativo:

1. Inicie sessão no portal do Azure.

2. Se você tiver acesso a vários locatários, use o filtro Diretório + assinatura ( ) para selecionar o locatário no qual deseja registrar um aplicativo.

3. Procure e selecione Microsoft Entra ID.

4. Em Gerir, selecione Registos de>aplicações Novo registo.

5. Insira um nome para seu aplicativo no campo Nome - por exemplo, ToDoWeb. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.

6. Para Tipos de conta suportados, use o valor padrão Contas somente neste diretório organizacional.

7. Selecione Registar para criar a aplicação.

8. Na página Visão geral do aplicativo, procure o valor da ID do aplicativo (cliente) e registre-o para uso posterior. Você precisa dele para adquirir um token de acesso.

9. Selecione Permissões>de API Adicionar uma permissão>Minhas APIs. Selecione o ToDo aplicativo que você registrou anteriormente e, em seguida, selecione as permissões ToDo.Read, ToDo.Write e ToDo.Delete. Selecione Adicionar permissões.

10. Selecione Conceder consentimento de administrador para <seu nome> de locatário para conceder consentimento de administrador para as permissões adicionadas.

    

Adicionar usuário para acessar as APIs RESTful

Use as etapas a seguir para criar um usuário membro em seu locatário do Microsoft Entra. Em seguida, o usuário pode gerenciar os ToDo dados do aplicativo por meio de APIs RESTful.

1. Em Gerenciar, selecione Usuários>Novo usuário>Criar novo usuário.

2. Na página Criar novo usuário, insira as seguintes informações:

   • Nome principal do usuário: insira um nome para o usuário.
   • Nome para exibição: insira um nome para exibição para o usuário.
   • Senha: copie a senha gerada automaticamente fornecida na caixa Senha .

   Nota

   Novos usuários devem concluir a primeira autenticação de entrada e atualizar suas senhas, caso contrário, você receberá um AADSTS50055: The password is expired erro quando receber o token de acesso.

   Quando um novo usuário faz login, ele recebe um prompt de Ação necessária . Eles podem escolher Perguntar mais tarde para ignorar a validação.

3. Selecione Rever + criar para rever as suas seleções. Selecione Criar para criar o usuário.

Atualizar a configuração OAuth2 para autorização da interface do usuário do Swagger

Use as etapas a seguir para atualizar a configuração OAuth2 para autorização da interface do usuário do Swagger. Em seguida, você pode autorizar os usuários a adquirir tokens de acesso por meio do ToDoWeb aplicativo.

1. Abra seu locatário do Microsoft Entra ID no portal do Azure e vá para o aplicativo registrado ToDoWeb .

2. Em Gerir, selecione Autenticação, selecione Adicionar uma plataforma e, em seguida, selecione Aplicação de página única.

3. Use o formato <your-app-exposed-application-URL-or-endpoint>/swagger-ui/oauth2-redirect.html como a URL de redirecionamento OAuth2 no campo URIs de redirecionamento e selecione Configurar.

   

Obter o token de acesso

Use as seguintes etapas para usar o método de fluxo de código de autorização OAuth 2.0 para obter um token de acesso com o Microsoft Entra ID e, em seguida, acessar as APIs RESTful do ToDo aplicativo:

1. Abra o URL exposto pelo aplicativo e selecione Autorizar para preparar a autenticação OAuth2.

2. Na janela Autorizações disponíveis, insira a ToDoWeb ID do cliente do aplicativo no campo client_id, selecione todos os escopos para o campo Escopos, ignore o campo client_secret e selecione Autorizar para redirecionar para a página de entrada do Microsoft Entra.

Depois de concluir o login com o usuário anterior, você retornará à janela Autorizações disponíveis.

5.2. Acesse as APIs RESTful

Use as seguintes etapas para acessar as APIs RESTful do ToDo aplicativo na interface do usuário do Swagger:

1. Selecione a API POST /api/simple-todo/lists e, em seguida, selecione Experimentar. Insira o seguinte corpo da solicitação e selecione Executar para criar uma lista de Tarefas Pendentes.

   {
     "name": "My List"
   }
   

   Após a conclusão da execução, você verá o seguinte corpo de resposta:

   {
     "id": "<ID-of-the-ToDo-list>",
     "name": "My List",
     "description": null
   }
   

2. Selecione a API POST /api/simple-todo/lists/{listId}/items e selecione Experimentar. Para listId, insira o ID da lista ToDo que você criou anteriormente, insira o seguinte corpo da solicitação e selecione Executar para criar um item ToDo.

   {
     "name": "My first ToDo item", 
     "listId": "<ID-of-the-ToDo-list>",
     "state": "todo"
   }
   

   Esta ação retorna o seguinte item ToDo:

   {
     "id": "<ID-of-the-ToDo-item>",
     "listId": "<ID-of-the-ToDo-list>",
     "name": "My first ToDo item",
     "description": null,
     "state": "todo",
     "dueDate": "2023-07-11T13:59:24.9033069+08:00",
     "completedDate": null
   }
   

3. Selecione a API GET /api/simple-todo/lists e, em seguida, selecione Executar para consultar listas de ToDo. Esta ação retorna as seguintes listas de ToDo:

   [
     {
       "id": "<ID-of-the-ToDo-list>",
       "name": "My List",
       "description": null
     }
   ]
   

4. Selecione a API GET /api/simple-todo/lists/{listId}/items e selecione Experimentar. Para listId, insira o ID da lista de ToDo que você criou anteriormente e selecione Executar para consultar os itens de ToDo. Esta ação retorna o seguinte item ToDo:

   [
     {
       "id": "<ID-of-the-ToDo-item>",
       "listId": "<ID-of-the-ToDo-list>",
       "name": "My first ToDo item",
       "description": null,
       "state": "todo",
       "dueDate": "2023-07-11T13:59:24.903307+08:00",
       "completedDate": null
     }
   ]
   

5. Selecione a API PUT /api/simple-todo/lists/{listId}/items/{itemId} e selecione Experimentar. Para listId, insira o ID da lista ToDo. Para itemId, insira a ID do item ToDo, insira o seguinte corpo da solicitação e selecione Executar para atualizar o item ToDo.

   {
     "id": "<ID-of-the-ToDo-item>",
     "listId": "<ID-of-the-ToDo-list>",
     "name": "My first ToDo item",
     "description": "Updated description.",
     "dueDate": "2023-07-11T13:59:24.903307+08:00",
     "state": "inprogress"
   }
   

   Esta ação retorna o seguinte item ToDo atualizado:

   {
     "id": "<ID-of-the-ToDo-item>",
     "listId": "<ID-of-the-ToDo-list>",
     "name": "My first ToDo item",
     "description": "Updated description.",
     "state": "inprogress",
     "dueDate": "2023-07-11T05:59:24.903307Z",
     "completedDate": null
   }
   

6. Selecione a API DELETE /api/simple-todo/lists/{listId}/items/{itemId} e selecione Experimentar. Para listId, insira o ID da lista ToDo. Para itemId, insira a ID do item ToDo e selecione Executar para excluir o item ToDo. Você deve ver que o código de resposta do servidor é 204.

6. Limpar os recursos

Pode eliminar o grupo de recursos do Azure, que inclui todos os recursos no grupo de recursos.

Portal do Azure + plug-in Maven

Use as seguintes etapas para excluir todo o grupo de recursos, incluindo o serviço recém-criado:

1. Localize o grupo de recursos no portal do Azure.

2. No menu de navegação, selecione Grupos de recursos. Em seguida, selecione o nome do seu grupo de recursos - por exemplo, myresourcegroup.

3. Na página do grupo de recursos, selecione Eliminar. Digite o nome do seu grupo de recursos na caixa de texto para confirmar a exclusão - por exemplo, myresourcegroup. Em seguida, selecione Excluir.

CLI do Azure

Use o seguinte comando para excluir todo o grupo de recursos, incluindo o serviço recém-criado:

az group delete --name ${RESOURCE_GROUP}

Portal do Azure + plug-in Maven

Use as seguintes etapas para excluir todo o grupo de recursos, incluindo o serviço recém-criado:

1. Localize o grupo de recursos no portal do Azure.

2. No menu de navegação, selecione Grupos de recursos. Em seguida, selecione o nome do seu grupo de recursos - por exemplo, myresourcegroup.

3. Na página do grupo de recursos, selecione Eliminar. Digite o nome do seu grupo de recursos na caixa de texto para confirmar a exclusão - por exemplo, myresourcegroup. Em seguida, selecione Excluir.

CLI do desenvolvedor do Azure

Use o seguinte comando para excluir todos os recursos do Azure usados neste aplicativo de exemplo:

azd down

A lista a seguir descreve a interação de comando:

• Total de recursos a eliminar: [seu-total-recursos], tem a certeza de que pretende continuar?: Prima y.

O console emite mensagens semelhantes ao exemplo a seguir:

SUCCESS: Your application was removed from Azure in xx minutes xx seconds.

7. Próximas etapas

Guia de início rápido: implantar um aplicativo controlado por eventos no Azure Spring Apps

Guia de início rápido: implantar aplicativos de microsserviço no Azure Spring Apps

Log de aplicativo estruturado para Azure Spring Apps

Mapear um domínio personalizado existente para o Azure Spring Apps

Usar o Azure Spring Apps CI/CD com ações do GitHub

Automatize implantações de aplicativos no Azure Spring Apps

Para obter mais informações, consulte os seguintes artigos:

• Exemplos de aplicativos do Azure Spring.
• Spring no Azure
• Spring Cloud Azure