Partilhar via

Guia de início rápido: criar um novo projeto de API com TypeSpec e .NET

Neste guia de início rápido, você aprenderá a usar o TypeSpec para projetar, gerar e implementar um aplicativo de API RESTful. TypeSpec é uma linguagem de código aberto para descrever APIs de serviço de nuvem e gera código de cliente e servidor para várias plataformas. Seguindo este guia de início rápido, você aprende a definir seu contrato de API uma vez e gerar implementações consistentes, ajudando a criar serviços de API mais fáceis de manter e bem documentados.

Neste guia de início rápido, você irá:

  • Defina sua API usando TypeSpec
  • Criar um aplicativo de servidor de API
  • Integrar o Azure Cosmos DB para armazenamento persistente
  • Execute e teste sua API localmente
  • Implantar em aplicativos de contêiner do Azure

Prerequisites

Desenvolvendo com TypeSpec

O TypeSpec define sua API de forma independente de linguagem e gera o servidor de API e a biblioteca de cliente para várias plataformas. Esta funcionalidade permite-lhe:

  • Defina seu contrato de API uma vez
  • Gerar código consistente de servidor e cliente
  • Concentre-se na implementação da lógica de negócios em vez da infraestrutura de API

O TypeSpec fornece gerenciamento de serviços de API:

  • Linguagem de definição da API
  • Middleware de roteamento do lado do servidor para API
  • Bibliotecas de cliente para consumir API

Você fornece solicitações de cliente e integrações de servidor:

  • Implementar lógica de negócios em middleware, como serviços do Azure para bancos de dados, armazenamento e mensagens
  • Servidor de hospedagem para sua API (localmente ou no Azure)
  • Scripts de configuração para aprovisionamento e implantação repetível

Criar um novo aplicativo TypeSpec

  1. Crie uma nova pasta para armazenar o servidor de API e os arquivos TypeSpec.

    mkdir my_typespec_quickstart
cd my_typespec_quickstart

  2. Instale o compilador TypeSpec globalmente:

    npm install -g @typespec/compiler

  3. Verifique o TypeSpec instalado corretamente:

    tsp --version

  4. Inicialize o projeto TypeSpec:

    tsp init

  5. Responda às seguintes perguntas usando as respostas fornecidas.

    • Inicializar um novo projeto aqui? Y
    • Selecionar um modelo de projeto? API REST genérica
    • Insira um nome de projeto: Widgets
    • Que emissores pretende utilizar?
      • Documento OpenAPI 3.1
      • Stubs de servidor C#

    Os emissores TypeSpec são bibliotecas que utilizam várias APIs de compilador TypeSpec para refletir sobre o processo de compilação TypeSpec e gerar artefatos.

  6. Aguarde a conclusão da inicialização antes de continuar.

    Run tsp compile . to build the project.

Please review the following messages from emitters:
  @typespec/http-server-csharp: 

        Generated ASP.Net services require dotnet 9:
        https://dotnet.microsoft.com/download 

        Create an ASP.Net service project for your TypeSpec:
        > npx hscs-scaffold . --use-swaggerui --overwrite

        More information on getting started:
        https://aka.ms/tsp/hscs/start

  7. Compile o projeto:

    tsp compile .

  8. TypeSpec gera o projeto padrão no ./tsp-output, criando duas pastas separadas:

    • esquema
    • servidor

  9. Abra o ficheiro ./tsp-output/schema/openapi.yaml. Observe que as poucas linhas em ./main.tsp geraram mais de 200 linhas de especificação OpenApi para você.

  10. Abra a pasta ./tsp-output/server/aspnet. Observe que os arquivos .NET scaffolded incluem:

    • ./generated/operations/IWidgets.cs define a interface para os métodos Widgets.
    • ./generated/controllers/WidgetsController.cs implementa a integração com os métodos Widgets. É aqui que você coloca a sua lógica de negócios.
    • ./generated/models define os modelos para a API do widget.

Configurar emissores TypeSpec

Use os arquivos TypeSpec para configurar a geração do servidor de API.

  1. Abra o tsconfig.yaml e substitua a configuração existente pelo seguinte YAML:

    emit:
  - "@typespec/openapi3"
  - "@typespec/http-server-csharp"
options:
  "@typespec/openapi3":
    emitter-output-dir: "{cwd}/server/wwwroot"
    openapi-versions:
      - 3.1.0
  "@typespec/http-server-csharp":
    emitter-output-dir: "{cwd}/server/"
    use-swaggerui: true
    overwrite: true
    emit-mocks: "mocks-and-project-files"

    Esta configuração projeta várias alterações que precisamos para um servidor de API .NET totalmente gerado:

    • emit-mocks: Crie todos os arquivos de projeto necessários para o servidor.
    • use-swaggerui: Integre a interface do usuário do Swagger para que você possa usar a API de uma maneira amigável para o navegador.
    • emitter-output-dir: Configure o diretório de saída tanto para geração de servidor como para geração de especificação OpenApi.
    • Gere tudo em ./server.

  2. Recompile o projeto:

    tsp compile .

  3. Mude para o novo /server diretório:

    cd server

  4. Crie um certificado de desenvolvedor padrão se ainda não tiver um:

    dotnet dev-certs https

  5. Execute o projeto:

    dotnet run

    Aguarde até que a notificação seja aberta no navegador.

  6. Abra o navegador e adicione a rota do Swagger UI, /swagger.

    Uma captura de tela mostrando a interface do usuário do Swagger com a API de widgets.

  7. A API TypeSpec padrão e o servidor funcionam.

Compreender a estrutura do arquivo do aplicativo

A estrutura do projeto para o servidor gerado inclui o servidor de API baseado em controlador .NET, os arquivos .NET para criar o projeto e o middleware para sua integração com o Azure.

├── appsettings.Development.json
├── appsettings.json
├── docs
├── generated
├── mocks
├── Program.cs
├── Properties
├── README.md
├── ServiceProject.csproj
└── wwwroot
  • Adicione sua lógica de negócios: neste exemplo, comece com o ./server/mocks/Widget.cs arquivo. O gerador Widget.cs fornece métodos padrão.
  • Atualizar o servidor: adicione quaisquer configurações específicas do servidor ao ./program.cs.
  • Use a especificação OpenApi: o TypeSpec gerou o ficheiro OpenApi3.json no ./server/wwwroot ficheiro e disponibilizou-o ao Swagger UI durante o desenvolvimento. Isso fornece uma interface do usuário para sua especificação. Você pode interagir com sua API sem precisar fornecer um mecanismo de solicitação, como um cliente REST ou front-end da Web.

Alterar a persistência para o Azure Cosmos DB NoSQL

Agora que o servidor básico da API de Widget está funcionando, atualize o servidor para trabalhar com o Azure Cosmos DB para um armazenamento de dados persistente.

  1. No diretório, adicione o ./serverAzure Cosmos DB ao projeto:

    dotnet add package Microsoft.Azure.Cosmos

  2. Adicione a biblioteca de Identidade do Azure para autenticar no Azure:

    dotnet add package Azure.Identity

  3. Atualize as configurações de integração do ./server/ServiceProject.csproj Cosmos DB:

    <Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    ... existing settings ...
    <EnableSdkContainerSupport>true</EnableSdkContainerSupport>
  </PropertyGroup>
  <ItemGroup>
    ... existing settings ...
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>
    • EnableSdkContainerSupport permite que você use o suporte de compilação de contêiner interno do SDK do .NET (dotnet publish ––container) sem escrever um Dockerfile.
    • Newtonsoft.Json adiciona o serializador Json .NET que o SDK do Cosmos DB usa para converter os seus objetos .NET para e a partir de JSON.

  4. Crie um novo arquivo ./azure/CosmosDbRegistration de registro para gerenciar o registro do Cosmos DB:

    using Microsoft.Azure.Cosmos;
using Microsoft.Extensions.Configuration;
using System;
using System.Threading.Tasks;
using Azure.Identity;
using DemoService;

namespace WidgetService.Service
{
    /// <summary>
    /// Registration class for Azure Cosmos DB services and implementations
    /// </summary>
    public static class CosmosDbRegistration
    {
        /// <summary>
        /// Registers the Cosmos DB client and related services for dependency injection
        /// </summary>
        /// <param name="builder">The web application builder</param>
        public static void RegisterCosmosServices(this WebApplicationBuilder builder)
        {
            // Register the HttpContextAccessor for accessing the HTTP context
            builder.Services.AddHttpContextAccessor();

            // Get configuration settings
            var cosmosEndpoint = builder.Configuration["Configuration:AzureCosmosDb:Endpoint"];

            // Validate configuration
            ValidateCosmosDbConfiguration(cosmosEndpoint);

            // Configure Cosmos DB client options
            var cosmosClientOptions = new CosmosClientOptions
            {
                SerializerOptions = new CosmosSerializationOptions
                {
                    PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
                },
                ConnectionMode = ConnectionMode.Direct
            };

            builder.Services.AddSingleton(serviceProvider =>
            {
                var credential = new DefaultAzureCredential();

                // Create Cosmos client with token credential authentication
                return new CosmosClient(cosmosEndpoint, credential, cosmosClientOptions);
            });

            // Initialize Cosmos DB if needed
            builder.Services.AddHostedService<CosmosDbInitializer>();

            // Register WidgetsCosmos implementation of IWidgets
            builder.Services.AddScoped<IWidgets, WidgetsCosmos>();
        }

        /// <summary>
        /// Validates the Cosmos DB configuration settings
        /// </summary>
        /// <param name="cosmosEndpoint">The Cosmos DB endpoint</param>
        /// <exception cref="ArgumentException">Thrown when configuration is invalid</exception>
        private static void ValidateCosmosDbConfiguration(string cosmosEndpoint)
        {
            if (string.IsNullOrEmpty(cosmosEndpoint))
            {
                throw new ArgumentException("Cosmos DB Endpoint must be specified in configuration");
            }
        }
    }
}

    Observe a variável de ambiente para o ponto de extremidade:

    var cosmosEndpoint = builder.Configuration["Configuration:AzureCosmosDb:Endpoint"];

  5. Crie uma nova classe ./azure/WidgetsCosmos.cs Widget para fornecer lógica de negócios para integração com o Azure Cosmos DB para sua loja persistente.

    using System;
using System.Net;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;
using Microsoft.Extensions.Logging;
using System.Collections.Generic;
using System.Linq;

// Use generated models and operations
using DemoService;

namespace WidgetService.Service
{
    /// <summary>
    /// Implementation of the IWidgets interface that uses Azure Cosmos DB for persistence
    /// </summary>
    public class WidgetsCosmos : IWidgets
    {
        private readonly CosmosClient _cosmosClient;
        private readonly ILogger<WidgetsCosmos> _logger;
        private readonly IHttpContextAccessor _httpContextAccessor;
        private readonly string _databaseName = "WidgetDb";
        private readonly string _containerName = "Widgets";

        /// <summary>
        /// Initializes a new instance of the WidgetsCosmos class.
        /// </summary>
        /// <param name="cosmosClient">The Cosmos DB client instance</param>
        /// <param name="logger">Logger for diagnostic information</param>
        /// <param name="httpContextAccessor">Accessor for the HTTP context</param>
        public WidgetsCosmos(
            CosmosClient cosmosClient,
            ILogger<WidgetsCosmos> logger,
            IHttpContextAccessor httpContextAccessor)
        {
            _cosmosClient = cosmosClient;
            _logger = logger;
            _httpContextAccessor = httpContextAccessor;
        }

        /// <summary>
        /// Gets a reference to the Cosmos DB container for widgets
        /// </summary>
        private Container WidgetsContainer => _cosmosClient.GetContainer(_databaseName, _containerName);

        /// <summary>
        /// Lists all widgets in the database
        /// </summary>
        /// <returns>Array of Widget objects</returns>
        public async Task<WidgetList> ListAsync()
        {
            try
            {
                var queryDefinition = new QueryDefinition("SELECT * FROM c");
                var widgets = new List<Widget>();

                using var iterator = WidgetsContainer.GetItemQueryIterator<Widget>(queryDefinition);
                while (iterator.HasMoreResults)
                {
                    var response = await iterator.ReadNextAsync();
                    widgets.AddRange(response.ToList());
                }

                // Create and return a WidgetList instead of Widget[]
                return new WidgetList
                {
                    Items = widgets.ToArray()
                };
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error listing widgets from Cosmos DB");
                throw new Error(500, "Failed to retrieve widgets from database");
            }
        }

        /// <summary>
        /// Retrieves a specific widget by ID
        /// </summary>
        /// <param name="id">The ID of the widget to retrieve</param>
        /// <returns>The retrieved Widget</returns>
        public async Task<Widget> ReadAsync(string id)
        {
            try
            {
                var response = await WidgetsContainer.ReadItemAsync<Widget>(
                    id, new PartitionKey(id));

                return response.Resource;
            }
            catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
            {
                _logger.LogWarning("Widget with ID {WidgetId} not found", id);
                throw new Error(404, $"Widget with ID '{id}' not found");
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error reading widget {WidgetId} from Cosmos DB", id);
                throw new Error(500, "Failed to retrieve widget from database");
            }
        }
        /// <summary>
        /// Creates a new widget from the provided Widget object
        /// </summary>
        /// <param name="body">The Widget object to store in the database</param>
        /// <returns>The created Widget</returns>
        public async Task<Widget> CreateAsync(Widget body)
        {
            try
            {
                // Validate the Widget
                if (body == null)
                {
                    throw new Error(400, "Widget data cannot be null");
                }

                if (string.IsNullOrEmpty(body.Id))
                {
                    throw new Error(400, "Widget must have an Id");
                }

                if (body.Color != "red" && body.Color != "blue")
                {
                    throw new Error(400, "Color must be 'red' or 'blue'");
                }

                // Save the widget to Cosmos DB
                var response = await WidgetsContainer.CreateItemAsync(
                    body, new PartitionKey(body.Id));

                _logger.LogInformation("Created widget with ID {WidgetId}", body.Id);
                return response.Resource;
            }
            catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
            {
                _logger.LogError(ex, "Widget with ID {WidgetId} already exists", body.Id);
                throw new Error(409, $"Widget with ID '{body.Id}' already exists");
            }
            catch (Exception ex) when (!(ex is Error))
            {
                _logger.LogError(ex, "Error creating widget in Cosmos DB");
                throw new Error(500, "Failed to create widget in database");
            }
        }

        /// <summary>
        /// Updates an existing widget with properties specified in the patch document
        /// </summary>
        /// <param name="id">The ID of the widget to update</param>
        /// <param name="body">The WidgetMergePatchUpdate object containing properties to update</param>
        /// <returns>The updated Widget</returns>
        public async Task<Widget> UpdateAsync(string id, TypeSpec.Http.WidgetMergePatchUpdate body)
        {
            try
            {
                // Validate input parameters
                if (body == null)
                {
                    throw new Error(400, "Update data cannot be null");
                }

                if (body.Color != null && body.Color != "red" && body.Color != "blue")
                {
                    throw new Error(400, "Color must be 'red' or 'blue'");
                }

                // First check if the item exists
                Widget existingWidget;
                try
                {
                    var response = await WidgetsContainer.ReadItemAsync<Widget>(
                        id, new PartitionKey(id));
                    existingWidget = response.Resource;
                }
                catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
                {
                    _logger.LogWarning("Widget with ID {WidgetId} not found for update", id);
                    throw new Error(404, $"Widget with ID '{id}' not found");
                }

                // Apply the patch updates only where properties are provided
                bool hasChanges = false;

                if (body.Weight.HasValue)
                {
                    existingWidget.Weight = body.Weight.Value;
                    hasChanges = true;
                }

                if (body.Color != null)
                {
                    existingWidget.Color = body.Color;
                    hasChanges = true;
                }

                // Only perform the update if changes were made
                if (hasChanges)
                {
                    // Use ReplaceItemAsync for the update
                    var updateResponse = await WidgetsContainer.ReplaceItemAsync(
                        existingWidget, id, new PartitionKey(id));

                    _logger.LogInformation("Updated widget with ID {WidgetId}", id);
                    return updateResponse.Resource;
                }

                // If no changes, return the existing widget
                _logger.LogInformation("No changes to apply for widget with ID {WidgetId}", id);
                return existingWidget;
            }
            catch (Error)
            {
                // Rethrow Error exceptions
                throw;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error updating widget {WidgetId} in Cosmos DB", id);
                throw new Error(500, "Failed to update widget in database");
            }
        }

        /// <summary>
        /// Deletes a widget by its ID
        /// </summary>
        /// <param name="id">The ID of the widget to delete</param>
        public async Task DeleteAsync(string id)
        {
            try
            {
                await WidgetsContainer.DeleteItemAsync<Widget>(id, new PartitionKey(id));
                _logger.LogInformation("Deleted widget with ID {WidgetId}", id);
            }
            catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
            {
                _logger.LogWarning("Widget with ID {WidgetId} not found for deletion", id);
                throw new Error(404, $"Widget with ID '{id}' not found");
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error deleting widget {WidgetId} from Cosmos DB", id);
                throw new Error(500, "Failed to delete widget from database");
            }
        }

        /// <summary>
        /// Analyzes a widget by ID and returns a simplified analysis result
        /// </summary>
        /// <param name="id">The ID of the widget to analyze</param>
        /// <returns>An AnalyzeResult containing the analysis of the widget</returns>
        public async Task<AnalyzeResult> AnalyzeAsync(string id)
        {
            try
            {
                // First retrieve the widget from the database
                Widget widget;
                try
                {
                    var response = await WidgetsContainer.ReadItemAsync<Widget>(
                        id, new PartitionKey(id));
                    widget = response.Resource;
                }
                catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
                {
                    _logger.LogWarning("Widget with ID {WidgetId} not found for analysis", id);
                    throw new Error(404, $"Widget with ID '{id}' not found");
                }

                // Create the analysis result
                var result = new AnalyzeResult
                {
                    Id = widget.Id,
                    Analysis = $"Weight: {widget.Weight}, Color: {widget.Color}"
                };

                _logger.LogInformation("Analyzed widget with ID {WidgetId}", id);
                return result;
            }
            catch (Error)
            {
                // Rethrow Error exceptions
                throw;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error analyzing widget {WidgetId} from Cosmos DB", id);
                throw new Error(500, "Failed to analyze widget from database");
            }
        }
    }
}

  6. Crie o ./server/services/CosmosDbInitializer.cs arquivo para autenticar no Azure:

    using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

namespace WidgetService.Service
{
    /// <summary>
    /// Hosted service that initializes Cosmos DB resources on application startup
    /// </summary>
    public class CosmosDbInitializer : IHostedService
    {
        private readonly CosmosClient _cosmosClient;
        private readonly ILogger<CosmosDbInitializer> _logger;
        private readonly IConfiguration _configuration;
        private readonly string _databaseName;
        private readonly string _containerName = "Widgets";

        public CosmosDbInitializer(CosmosClient cosmosClient, ILogger<CosmosDbInitializer> logger, IConfiguration configuration)
        {
            _cosmosClient = cosmosClient;
            _logger = logger;
            _configuration = configuration;
            _databaseName = _configuration["CosmosDb:DatabaseName"] ?? "WidgetDb";
        }

        public async Task StartAsync(CancellationToken cancellationToken)
        {
            _logger.LogInformation("Ensuring Cosmos DB database and container exist...");

            try
            {
                // Create database if it doesn't exist
                var databaseResponse = await _cosmosClient.CreateDatabaseIfNotExistsAsync(
                    _databaseName,
                    cancellationToken: cancellationToken);

                _logger.LogInformation("Database {DatabaseName} status: {Status}", _databaseName,
                    databaseResponse.StatusCode == System.Net.HttpStatusCode.Created ? "Created" : "Already exists");

                // Create container if it doesn't exist (using id as partition key)
                var containerResponse = await databaseResponse.Database.CreateContainerIfNotExistsAsync(
                    new ContainerProperties
                    {
                        Id = _containerName,
                        PartitionKeyPath = "/id"
                    },
                    throughput: 400, // Minimum RU/s
                    cancellationToken: cancellationToken);

                _logger.LogInformation("Container {ContainerName} status: {Status}", _containerName,
                    containerResponse.StatusCode == System.Net.HttpStatusCode.Created ? "Created" : "Already exists");
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error initializing Cosmos DB");
                throw;
            }
        }

        public Task StopAsync(CancellationToken cancellationToken)
        {
            return Task.CompletedTask;
        }
    }
}

  7. Atualize ./server/program.cs para usar Cosmos DB e permitir que o Swagger UI seja usado em uma implantação de produção. Copie em todo o arquivo:

    // Generated by @typespec/http-server-csharp
// <auto-generated />
#nullable enable

using TypeSpec.Helpers;
using WidgetService.Service;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllersWithViews(options =>
{
    options.Filters.Add<HttpServiceExceptionFilter>();
});
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Replace original registration with the Cosmos DB one
CosmosDbRegistration.RegisterCosmosServices(builder);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

// Swagger UI is always available
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.DocumentTitle = "TypeSpec Generated OpenAPI Viewer";
    c.SwaggerEndpoint("/openapi.yaml", "TypeSpec Generated OpenAPI Docs");
    c.RoutePrefix = "swagger";
});

app.UseHttpsRedirection();
app.UseStaticFiles();
app.Use(async (context, next) =>
{
    context.Request.EnableBuffering();
    await next();
});

app.MapGet("/openapi.yaml", async (HttpContext context) =>
{
    var externalFilePath = "wwwroot/openapi.yaml"; 
    if (!File.Exists(externalFilePath))
    {
        context.Response.StatusCode = StatusCodes.Status404NotFound;
        await context.Response.WriteAsync("OpenAPI spec not found.");
        return;
    }
    context.Response.ContentType = "application/json";
    await context.Response.SendFileAsync(externalFilePath);
});

app.UseRouting();
app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

  8. Compile o projeto:

    dotnet build

    O projeto agora é construído com integração com o Cosmos DB. Vamos criar os scripts de implantação para criar os recursos do Azure e implantar o projeto.

Criar infraestrutura de implantação

Crie os ficheiros necessários para ter uma implementação repetível com a Azure Developer CLI e modelos Bicep.

  1. Na raiz do projeto TypeSpec, crie um azure.yaml ficheiro de definição de implantação e cole o seguinte código:

    # yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json

name: azure-typespec-scaffold-dotnet
metadata:
    template: azd-init@1.14.0
services:
    api:
        project: ./server
        host: containerapp
        language: dotnet
pipeline:
  provider: github

    Observe que essa configuração faz referência ao local do projeto gerado (./server). ./tspconfig.yaml Verifique se corresponde ao local especificado em ./azure.yaml.

  2. Na raiz do projeto TypeSpec, crie um ./infra diretório.

  3. Crie um ./infra/main.bicepparam arquivo e copie o seguinte para definir os parâmetros necessários para a implantação:

    using './main.bicep'

param environmentName = readEnvironmentVariable('AZURE_ENV_NAME', 'dev')
param location = readEnvironmentVariable('AZURE_LOCATION', 'eastus2')
param deploymentUserPrincipalId = readEnvironmentVariable('AZURE_PRINCIPAL_ID', '')

    Esta lista de parâmetros fornece os parâmetros mínimos necessários para esta implantação.

  4. Crie um ./infra/main.bicep arquivo e copie o seguinte para definir os recursos do Azure para provisionamento e implantação:

    metadata description = 'Bicep template for deploying a GitHub App using Azure Container Apps and Azure Container Registry.'

targetScope = 'resourceGroup'
param serviceName string = 'api'
var databaseName = 'WidgetDb'
var containerName = 'Widgets'

@minLength(1)
@maxLength(64)
@description('Name of the environment that can be used as part of naming resource convention')
param environmentName string

@minLength(1)
@description('Primary location for all resources')
param location string

@description('Id of the principal to assign database and application roles.')
param deploymentUserPrincipalId string = ''

var resourceToken = toLower(uniqueString(resourceGroup().id, environmentName, location))

var tags = {
  'azd-env-name': environmentName
  repo: 'https://github.com/typespec'
}

module managedIdentity 'br/public:avm/res/managed-identity/user-assigned-identity:0.4.1' = {
  name: 'user-assigned-identity'
  params: {
    name: 'identity-${resourceToken}'
    location: location
    tags: tags
  }
}

module cosmosDb 'br/public:avm/res/document-db/database-account:0.8.1' = {
  name: 'cosmos-db-account'
  params: {
    name: 'cosmos-db-nosql-${resourceToken}'
    location: location
    locations: [
      {
        failoverPriority: 0
        locationName: location
        isZoneRedundant: false
      }
    ]
    tags: tags
    disableKeyBasedMetadataWriteAccess: true
    disableLocalAuth: true
    networkRestrictions: {
      publicNetworkAccess: 'Enabled'
      ipRules: []
      virtualNetworkRules: []
    }
    capabilitiesToAdd: [
      'EnableServerless'
    ]
    sqlRoleDefinitions: [
      {
        name: 'nosql-data-plane-contributor'
        dataAction: [
          'Microsoft.DocumentDB/databaseAccounts/readMetadata'
          'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*'
          'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*'
        ]
      }
    ]
    sqlRoleAssignmentsPrincipalIds: union(
      [
        managedIdentity.outputs.principalId
      ],
      !empty(deploymentUserPrincipalId) ? [deploymentUserPrincipalId] : []
    )
    sqlDatabases: [
      {
        name: databaseName
        containers: [
          {
            name: containerName
            paths: [
              '/id'
            ]
          }
        ]
      }
    ]
  }
}

module containerRegistry 'br/public:avm/res/container-registry/registry:0.5.1' = {
  name: 'container-registry'
  params: {
    name: 'containerreg${resourceToken}'
    location: location
    tags: tags
    acrAdminUserEnabled: false
    anonymousPullEnabled: true
    publicNetworkAccess: 'Enabled'
    acrSku: 'Standard'
  }
}

var containerRegistryRole = subscriptionResourceId(
  'Microsoft.Authorization/roleDefinitions',
  '8311e382-0749-4cb8-b61a-304f252e45ec'
) 

module registryUserAssignment 'br/public:avm/ptn/authorization/resource-role-assignment:0.1.1' = if (!empty(deploymentUserPrincipalId)) {
  name: 'container-registry-role-assignment-push-user'
  params: {
    principalId: deploymentUserPrincipalId
    resourceId: containerRegistry.outputs.resourceId
    roleDefinitionId: containerRegistryRole
  }
}

module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.7.0' = {
  name: 'log-analytics-workspace'
  params: {
    name: 'log-analytics-${resourceToken}'
    location: location
    tags: tags
  }
}

module containerAppsEnvironment 'br/public:avm/res/app/managed-environment:0.8.0' = {
  name: 'container-apps-env'
  params: {
    name: 'container-env-${resourceToken}'
    location: location
    tags: tags
    logAnalyticsWorkspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
    zoneRedundant: false
  }
}

module containerAppsApp 'br/public:avm/res/app/container-app:0.9.0' = {
  name: 'container-apps-app'
  params: {
    name: 'container-app-${resourceToken}'
    environmentResourceId: containerAppsEnvironment.outputs.resourceId
    location: location
    tags: union(tags, { 'azd-service-name': serviceName })
    ingressTargetPort: 8080
    ingressExternal: true
    ingressTransport: 'auto'
    stickySessionsAffinity: 'sticky'
    scaleMaxReplicas: 1
    scaleMinReplicas: 1
    corsPolicy: {
      allowCredentials: true
      allowedOrigins: [
        '*'
      ]
    }
    managedIdentities: {
      systemAssigned: false
      userAssignedResourceIds: [
        managedIdentity.outputs.resourceId
      ]
    }
    secrets: {
      secureList: [
        {
          name: 'azure-cosmos-db-nosql-endpoint'
          value: cosmosDb.outputs.endpoint
        }
        {
          name: 'user-assigned-managed-identity-client-id'
          value: managedIdentity.outputs.clientId
        }
      ]
    }
    containers: [
      {
        image: 'mcr.microsoft.com/dotnet/samples:aspnetapp-9.0'
        name: serviceName
        resources: {
          cpu: '0.25'
          memory: '.5Gi'
        }
        env: [
          {
            name: 'CONFIGURATION__AZURECOSMOSDB__ENDPOINT'
            secretRef: 'azure-cosmos-db-nosql-endpoint'
          }
          {
            name: 'AZURE_CLIENT_ID'
            secretRef: 'user-assigned-managed-identity-client-id'
          }
        ]
      }
    ]
  }
}

output CONFIGURATION__AZURECOSMOSDB__ENDPOINT string = cosmosDb.outputs.endpoint
output CONFIGURATION__AZURECOSMOSDB__DATABASENAME string = databaseName
output CONFIGURATION__AZURECOSMOSDB__CONTAINERNAME string = containerName

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerRegistry.outputs.loginServer

    As variáveis de saída permitem que você use os recursos de nuvem provisionados com seu desenvolvimento local.

  5. A tag containerAppsApp usa a variável serviceName (definida como api na parte superior do arquivo) e a api especificada em ./azure.yaml. Essa conexão informa à CLI do Desenvolvedor do Azure onde implantar o projeto .NET no recurso de hospedagem de Aplicativos de Contêiner do Azure.

    ...bicep...

module containerAppsApp 'br/public:avm/res/app/container-app:0.9.0' = {
  name: 'container-apps-app'
  params: {
    name: 'container-app-${resourceToken}'
    environmentResourceId: containerAppsEnvironment.outputs.resourceId
    location: location
    tags: union(tags, { 'azd-service-name': serviceName })                    <--------- `API`

...bicep..

Estrutura do projeto

A estrutura final do projeto inclui os arquivos de API TypeSpec, o servidor Express.js e os arquivos de implantação do Azure:

├── infra
├── tsp-output
├── .gitignore
├── .azure.yaml
├── Dockerfile
├── main.tsp
├── package-lock.json
├── package.json
├── tspconfig.yaml
Area Ficheiros/Diretórios
TypeSpec main.tsp, tspconfig.yaml
Express.js servidor ./tsp-output/server/ (inclui ficheiros gerados como controllers/, models/, ServiceProject.csproj)
Implantação da CLI do Azure Developer ./azure.yaml,./infra/

Implantar aplicativo no Azure

Você pode implantar este aplicativo no Azure usando os Aplicativos de Contêiner do Azure:

  1. Autentique-se na CLI do Azure Developer:

    azd auth login

  2. Implante em Aplicações de Contentores do Azure usando a CLI do Azure Developer:

    azd up

Use o aplicativo no navegador

Uma vez implantado, você pode:

  1. Acesse a interface do usuário do Swagger para testar sua API em /swagger.
  2. Use o recurso Experimente agora em cada API para criar, ler, atualizar e excluir widgets por meio da API.

Aumente a sua aplicação

Agora que você tem todo o processo de ponta a ponta funcionando, continue a criar sua API:

  • Saiba mais sobre a linguagem TypeSpec para adicionar mais APIs e funcionalidades à camada de API no ./main.tsp.
  • Adicione emissores adicionais e configure seus parâmetros no ./tspconfig.yaml.
  • À medida que você adiciona mais recursos em seus arquivos TypeSpec, ofereça suporte a essas alterações com código-fonte no projeto de servidor.
  • Continue a usar a autenticação sem senha com a Identidade do Azure.

Limpeza de recursos

Quando terminar este início rápido, você poderá remover os recursos do Azure:

azd down

Ou exclua o grupo de recursos diretamente do portal do Azure.

Próximos passos

  • Last updated on