Rövid útmutató: Új API-projekt létrehozása TypeSpec és TypeScript használatával

Ebben a rövid útmutatóban megtudhatja, hogyan tervezhet, hozhat létre és implementálhat a TypeSpec használatával RESTful TypeScript API-alkalmazásokat. A TypeSpec egy nyílt forráskódú nyelv a felhőszolgáltatás API-k leírásához, és több platform ügyfél- és kiszolgálókódját hozza létre. A rövid útmutatót követve megtanulhatja, hogyan határozhatja meg egyszer az API-szerződést, és hogyan hozhat létre konzisztens implementációkat, segítve a karbantartható és jól dokumentált API-szolgáltatások kiépítését.

Ebben a gyors kezdő útmutatóban a következőket teheti meg:

Az API definiálása a TypeSpec használatával
API-kiszolgálóalkalmazás létrehozása
Az Azure Cosmos DB integrálása állandó tároláshoz
Telepítés az Azure-ra
Az API futtatása és tesztelése

Important

@typespec/http-server-js az emitter jelenleg előzetes verzióban érhető el. Ezek az információk egy előzetes termékre vonatkoznak, amely a kiadás előtt jelentősen módosítható. A Microsoft nem vállal kifejezett vagy hallgatólagos szavatosságot az itt megadott információkra vonatkozóan.

Prerequisites

Aktív Azure-fiók. Ha nincs fiókja, hozzon létre ingyenes fiókot .
Telepítve van a rendszerén a Node.js LTS.
TypeScript TypeScript-kód írásához és fordításához.
Docker
Visual Studio Code
TypeSpec kiterjesztés
Nem kötelező: Üzembe helyezés az Azure Developer CLI-vel

Fejlesztés a TypeSpec használatával

A TypeSpec nyelvfüggetlen módon határozza meg az API-t, és létrehozza az API-kiszolgálót és az ügyfélkódtárat több platformhoz. Ez a funkció a következő funkciókat teszi lehetővé:

API-szerződésed határozd meg egyszer
Konzisztens kiszolgáló- és ügyfélkód létrehozása
Az API-infrastruktúra helyett az üzleti logika implementálására összpontosítson

A TypeSpec API-szolgáltatáskezelést biztosít:

API-definíció nyelve
Kiszolgálóoldali útválasztási köztes szoftver API-hoz
Ügyfélkódtárak az API használatához

Ügyfélkéréseket és kiszolgálóintegrációkat biztosít:

Üzleti logika implementálása köztes szoftverben, például azure-szolgáltatások adatbázisokhoz, tároláshoz és üzenetkezeléshez
Kiszolgáló üzemeltetése az API-hoz (helyileg vagy az Azure-ban)
Üzembe helyezési szkriptek megismételhető erőforrás-előkészítéshez és üzembe helyezéshez

Új TypeSpec-alkalmazás létrehozása

Hozzon létre egy új mappát az API-kiszolgáló és a TypeSpec fájlok tárolásához.
```
mkdir my_typespec_quickstart
cd my_typespec_quickstart
```
Telepítse a TypeSpec fordítót globálisan:
```
npm install -g @typespec/compiler
```
Ellenőrizze, hogy a TypeSpec megfelelően van-e telepítve:
```
tsp --version
```
A TypeSpec projekt inicializálása:
```
tsp init
```
Válaszoljon a következő kérdésekre a megadott válaszokkal:
- Inicializál egy új projektet? Y
- Kiválaszt egy projektsablont? Általános REST API
- Projektnév megadása: Widgetek
- Milyen emittereket szeretne használni?
  - OpenAPI 3.1-dokumentum
  - JavaScript szerver csonkok
A TypeSpec emitterek olyan kódtárak, amelyek különböző TypeSpec fordító API-kat használnak a TypeSpec fordítási folyamatának tükrözésére és összetevők létrehozására.
A folytatás előtt várja meg, amíg az inicializálás befejeződik.
Fordítsa le a projektet:
```
tsp compile .
```
A TypeSpec létrehozza az alapértelmezett projektet a következő két külön mappában ./tsp-output:
- séma az OpenApi 3 specifikációja. Figyelje meg, hogy a néhány sor ./main.tsp több mint 200 sornyi OpenApi-specifikációt hozott létre Önnek.
- a kiszolgáló a létrehozott köztes szoftver. Ez a köztes szoftver egy Node.js kiszolgálóprojektbe építhető be.
  - ./tsp-output/js/src/generated/models/all/demo-service.ts meghatározza a Widgets API felületeit.
  - ./tsp-output/js/src/generated/http/openapi3.ts Az Open API-specifikációt TypeScript-fájlként definiálja, és a TypeSpec-projekt minden fordításakor újra létrejön.

TypeSpec emitterek konfigurálása

A TypeSpec-fájlokkal lehet konfigurálni az API szerver generálását az egész Express.js szerver felépítéséhez.

Nyissa meg a ./tsconfig.yaml meglévő konfigurációt, és cserélje le a következő YAML-re:
```
emit:
  - "@typespec/openapi3"
  - "@typespec/http-server-js"
options:
  "@typespec/openapi3":
    emitter-output-dir: "{output-dir}/server/schema"
    openapi-versions:
      - 3.1.0
  "@typespec/http-server-js":
    emitter-output-dir: "{output-dir}/server"
    express: true
```
Ez a konfiguráció létrehoz egy teljes Express.js API-kiszolgálót:
- express: Hozza létre a Express.js API-kiszolgálót, beleértve a Swagger felhasználói felületét is.
- emitter-output-dir: Generáljon mindent a ./server könyvtárba.
Törölje a meglévőt ./tsp-output. Ne aggódjon, a következő lépésben létrehozza a kiszolgálót.
A TypeSpec JavaScript-emitterrel hozza létre a Express.js kiszolgálót:
```
npx hsjs-scaffold
```
Váltás az új ./tsp-output/server könyvtárra:
```
cd ./tsp-output/server
```
A TypeScript fordítása JavaScriptre.
```
tsc
```
Futtassa a projektet:
```
npm start
```
Várja meg, amíg az értesítés megnyílik a böngészőben.
Nyissa meg a böngészőt, és látogassa meg a következőt http://localhost:3000/.api-docs.
Az alapértelmezett TypeSpec API és a kiszolgáló is működik. Ha be szeretné fejezni az API-kiszolgáló fejlesztését, adja hozzá üzleti logikáját a Widgets API-k támogatásához a ./tsp-output/server/src/controllers/widgets.ts szakaszban. A felhasználói felület csatlakozik az API-hoz, amely kemény kódolt hamis adatokat ad vissza.

Az alkalmazásfájl-struktúra ismertetése

A Express.js itt található tsp-output/server/ projektstruktúra tartalmazza a létrehozott kiszolgálót, a package.jsonés az Azure-integráció közbenső szoftverét.

server
├── package.json
├── package-lock.json
├── src
│   ├── controllers
│   │   └── widgets.ts
│   ├── generated
│   │   ├── helpers
│   │   │   ├── datetime.ts
│   │   │   ├── header.ts
│   │   │   ├── http.ts
│   │   │   ├── multipart.ts
│   │   │   ├── router.ts
│   │   │   └── temporal
│   │   │       ├── native.ts
│   │   │       └── polyfill.ts
│   │   ├── http
│   │   │   ├── openapi3.ts
│   │   │   ├── operations
│   │   │   │   └── server-raw.ts
│   │   │   └── router.ts
│   │   └── models
│   │       └── all
│   │           ├── demo-service.ts
│   │           └── typespec.ts
│   ├── index.ts
│   └── swagger-ui.ts

A szülő TypeSpec projekt fájlstruktúrája a következő Express.js projektet tsp-outputtartalmazza:

├── tsp-output
├── .gitignore
├── main.tsp
├── package-lock.json
├── package.json
├── tspconfig.yaml

Adatmegőrzés módosítása az Azure Cosmos DB no-sql-ra

Most, hogy az alapvető Express.js API-kiszolgáló működik, frissítse a Express.js-kiszolgálót, hogy az Azure Cosmos DB-vel működjön egy állandó adattárhoz. Ez magában foglalja a index.ts Cosmos DB-integráció közbenső szoftverben való használatának módosításait is. Minden módosításnak a ./tsp-output/server/src/generated könyvtáron kívül kell történnie.

A címtárban adja hozzá az ./tsp-output/serverAzure Cosmos DB-t a projekthez:
```
npm install @azure/cosmos
```
Adja hozzá az Azure Identity-kódtárat a hitelesítéshez az Azure-ban:
```
npm install @azure/identity
```
Hozzon létre egy könyvtárat ./tsp-output/server/src/azure az Azure-ra jellemző forráskód tárolásához.

Hozzon létre egy cosmosClient.ts fájlt abban a könyvtárban a Cosmos DB-ügyfélobjektum létrehozásához, és illessze be a következő kódot:

import { CosmosClient, Database, Container } from "@azure/cosmos";
import { DefaultAzureCredential } from "@azure/identity";

/**
 * Interface for CosmosDB configuration settings
 */
export interface CosmosConfig {
  endpoint: string;
  databaseId: string;
  containerId: string;
  partitionKey: string;
} 

/**
 * Singleton class for managing CosmosDB connections
 */
export class CosmosClientManager {
  private static instance: CosmosClientManager;
  private client: CosmosClient | null = null;
  private config: CosmosConfig | null = null;

  private constructor() {}

  /**
   * Get the singleton instance of CosmosClientManager
   */
  public static getInstance(): CosmosClientManager {
    if (!CosmosClientManager.instance) {
      CosmosClientManager.instance = new CosmosClientManager();
    }
    return CosmosClientManager.instance;
  }

  /**
   * Initialize the CosmosDB client with configuration if not already initialized
   * @param config CosmosDB configuration
   */
  private ensureInitialized(config: CosmosConfig): void {
    if (!this.client || !this.config) {
      this.config = config;
      this.client = new CosmosClient({
        endpoint: config.endpoint,
        aadCredentials: new DefaultAzureCredential(),
      });
    }
  }

  /**
   * Get a database instance, creating it if it doesn't exist
   * @param config CosmosDB configuration
   * @returns Database instance
   */
  private async getDatabase(config: CosmosConfig): Promise<Database> {
    this.ensureInitialized(config);
    const { database } = await this.client!.databases.createIfNotExists({ id: config.databaseId });
    return database;
  }

  /**
   * Get a container instance, creating it if it doesn't exist
   * @param config CosmosDB configuration
   * @returns Container instance
   */
  public async getContainer(config: CosmosConfig): Promise<Container> {
    const database = await this.getDatabase(config);
    const { container } = await database.containers.createIfNotExists({
      id: config.containerId,
      partitionKey: { paths: [config.partitionKey] }
    });
    return container;
  }

  /**
   * Clean up resources and close connections
   */
  public dispose(): void {
    this.client = null;
    this.config = null;
  }
}

export const buildError = (error: any, message: string) => {
  const statusCode = error?.statusCode || 500;
  return {
    code: statusCode,
    message: `${message}: ${error?.message || 'Unknown error'}`
  };
};

Figyelje meg, hogy a fájl a végpontot, az adatbázist és a tárolót használja. Nincs szüksége kapcsolati sztringre vagy kulcsra, mert az Azure Identity hitelesítő adatait DefaultAzureCredentialhasználja. Tudjon meg többet ennek a helyi és az éles környezetek biztonságos hitelesítésére szolgáló módszernek a működéséről.

Hozzon létre egy új widgetvezérlőt, ./tsp-output/server/src/controllers/WidgetsCosmos.tsés illessze be az alábbi integrációs kódot az Azure Cosmos DB-hez.

import { Widgets, Widget, WidgetList,   AnalyzeResult,Error } from "../generated/models/all/demo-service.js";
import { WidgetMergePatchUpdate } from "../generated/models/all/typespec/http.js";
import { CosmosClientManager, CosmosConfig, buildError } from "../azure/cosmosClient.js";
import { HttpContext } from "../generated/helpers/router.js";
import { Container } from "@azure/cosmos";

export interface WidgetDocument extends Widget {
  _ts?: number;
  _etag?: string;
}

/**
 * Implementation of the Widgets API using Azure Cosmos DB for storage
 */
export class WidgetsCosmosController implements Widgets<HttpContext>  {
  private readonly cosmosConfig: CosmosConfig;
  private readonly cosmosManager: CosmosClientManager;
  private container: Container | null = null;

  /**
   * Creates a new instance of WidgetsCosmosController
   * @param azureCosmosEndpoint Cosmos DB endpoint URL
   * @param databaseId The Cosmos DB database ID
   * @param containerId The Cosmos DB container ID
   * @param partitionKey The partition key path
   */
  constructor(azureCosmosEndpoint: string, databaseId: string, containerId: string, partitionKey: string) {
    if (!azureCosmosEndpoint) throw new Error("azureCosmosEndpoint is required");
    if (!databaseId) throw new Error("databaseId is required");
    if (!containerId) throw new Error("containerId is required");
    if (!partitionKey) throw new Error("partitionKey is required");

    this.cosmosConfig = {
      endpoint: azureCosmosEndpoint,
      databaseId: databaseId,
      containerId: containerId,
      partitionKey: partitionKey
    };

    this.cosmosManager = CosmosClientManager.getInstance();
  }

  /**
   * Get the container reference, with caching
   * @returns The Cosmos container instance
   */
  private async getContainer(): Promise<Container | null> {
    if (!this.container) {
      try {
        this.container = await this.cosmosManager.getContainer(this.cosmosConfig);
        return this.container;
      } catch (error: any) {
        console.error("Container initialization error:", error);
        throw buildError(error, `Failed to access container ${this.cosmosConfig.containerId}`);
      }
    }
    return this.container;
  }

  /**
   * Create a new widget
   * @param widget The widget to create
   * @returns The created widget with assigned ID
   */
  async create(ctx: HttpContext,
    body: Widget
  ): Promise<Widget | Error> {

    const id = body.id;

    try {
      const container = await this.getContainer();

      if(!container) {
        return buildError({statusCode:500}, "Container is not initialized");
      }

      if (!body.id) {
        return buildError({statusCode:400}, "Widget ID is required");
      }

      const response = await container.items.create<Widget>(body, { 
        disableAutomaticIdGeneration: true 
      });

      if (!response.resource) {
        return buildError({statusCode:500}, `Failed to create widget ${body.id}: No resource returned`);
      }

      return this.documentToWidget(response.resource);
    } catch (error: any) {
      if (error?.statusCode === 409) {
        return buildError({statusCode:409}, `Widget with id ${id} already exists`);
      }
      return buildError(error, `Failed to create widget ${id}`);
    }
  }

  /**
   * Delete a widget by ID
   * @param id The ID of the widget to delete
   */
  async delete(ctx: HttpContext, id: string): Promise<void | Error> {
    try {
      const container = await this.getContainer();

      if(!container) {
        return buildError({statusCode:500}, "Container is not initialized");
      }

      await container.item(id, id).delete();
    } catch (error: any) {
      if (error?.statusCode === 404) {
        return buildError({statusCode:404}, `Widget with id ${id} not found`);
      }
      return buildError(error, `Failed to delete widget ${id}`);
    }
  }

  /**
   * Get a widget by ID
   * @param id The ID of the widget to retrieve
   * @returns The widget if found
   */
  async read(ctx: HttpContext, id: string): Promise<Widget | Error> {
    try {
      const container = await this.getContainer();

      if(!container) {
        return buildError({statusCode:500}, "Container is not initialized");
      }

      const { resource } = await container.item(id, id).read<WidgetDocument>();

      if (!resource) {
        return buildError({statusCode:404}, `Widget with id ${id} not found`);
      }

      return this.documentToWidget(resource);
    } catch (error: any) {
      return buildError(error, `Failed to read widget ${id}`);
    }
  }

  /**
   * List all widgets with optional paging
   * @returns List of widgets
   */
  async list(ctx: HttpContext): Promise<WidgetList | Error> {
    try {
      const container = await this.getContainer();

      if(!container) {
        return buildError({statusCode:500}, "Container is not initialized");
      }

      const { resources } = await container.items
        .query({ query: "SELECT * FROM c" })
        .fetchAll();

      return { items: resources.map(this.documentToWidget) };
    } catch (error: any) {
      return buildError(error, "Failed to list widgets");
    }
  }

  /**
   * Update an existing widget
   * @param id The ID of the widget to update
   * @param body The partial widget data to update
   * @returns The updated widget
   */
  async update(
    ctx: HttpContext,
    id: string,
    body: WidgetMergePatchUpdate,
  ): Promise<Widget | Error> {
    try {
      const container = await this.getContainer();

      if(!container) {
        return buildError({statusCode:500}, "Container is not initialized");
      }

      // First check if the widget exists
      const { resource: item } = await container.item(id).read<WidgetDocument>();
      if (!item) {
        return buildError({statusCode:404}, `Widget with id ${id} not found`);
      }

      // Apply patch updates to the existing widget
      const updatedWidget: Widget = {
        ...item,
        ...body,
        id
      };

      // Replace the document in Cosmos DB
      const { resource } = await container.item(id).replace(updatedWidget);

      if (!resource) {
        return buildError({statusCode:500}, `Failed to update widget ${id}: No resource returned`);
      }

      return this.documentToWidget(resource);
    } catch (error: any) {
      return buildError(error, `Failed to update widget ${id}`);
    }
  }

  async analyze(ctx: HttpContext, id: string): Promise<AnalyzeResult | Error> {
    return {
      id: "mock-string",
      analysis: "mock-string",
    };
  }

  /**
   * Convert a Cosmos DB document to a Widget
   */
  private documentToWidget(doc: WidgetDocument): Widget {
    return Object.fromEntries(
      Object.entries(doc).filter(([key]) => !key.startsWith('_'))
    ) as Widget;
  }
}

Frissítse a ./tsp-output/server/src/index.ts-t az új vezérlő importálásához, kérje le az Azure Cosmos DB környezeti beállításait, majd hozza létre a WidgetsCosmosController-t, és adja át a routernek.

// Generated by Microsoft TypeSpec

import { WidgetsCosmosController } from "./controllers/WidgetsCosmos.js";

import { createDemoServiceRouter } from "./generated/http/router.js";

import express from "express";

import morgan from "morgan";

import { addSwaggerUi } from "./swagger-ui.js";

const azureCosmosEndpoint = process.env.AZURE_COSMOS_ENDPOINT!;
const azureCosmosDatabase = "WidgetDb";
const azureCosmosContainer = "Widgets";
const azureCosmosPartitionKey = "/Id";

const router = createDemoServiceRouter(
  new WidgetsCosmosController(
    azureCosmosEndpoint, 
    azureCosmosDatabase, 
    azureCosmosContainer, 
    azureCosmosPartitionKey)
);
const PORT = process.env.PORT || 3000;

const app = express();

app.use(morgan("dev"));

const SWAGGER_UI_PATH = process.env.SWAGGER_UI_PATH || "/.api-docs";

addSwaggerUi(SWAGGER_UI_PATH, app);

app.use(router.expressMiddleware);

app.listen(PORT, () => {
  console.log(`Server is running at http://localhost:${PORT}`);
  console.log(
    `API documentation is available at http://localhost:${PORT}${SWAGGER_UI_PATH}`,
  );
});

Egy terminálban ./tsp-output/serverállítsa le a TypeScriptet JavaScript-be.
```
tsc
```
A projekt most a Cosmos DB-integrációval épül fel. Hozzuk létre az üzembehelyezési szkripteket az Azure-erőforrások létrehozásához és a projekt üzembe helyezéséhez.

Üzembehelyezési infrastruktúra létrehozása

Hozza létre a megismételhető üzembe helyezéshez szükséges fájlokat az Azure Developer CLI-vel és a Bicep-sablonokkal.

A TypeSpec projekt gyökerénél hozzon létre egy azure.yaml üzembehelyezési definíciós fájlt, és illessze be a következő forrást:

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

name: azure-typespec-scaffold-js
metadata:
    template: azd-init@1.14.0
services:
    api:
        project: ./
        host: containerapp
        language: js
        docker:
            path: Dockerfile
pipeline:
  provider: github
hooks:
  postprovision:
    windows:
      shell: pwsh
      run: |
        # Set environment variables for the Container App
        azd env set AZURE_COSMOS_ENDPOINT "$env:AZURE_COSMOS_ENDPOINT"
      continueOnError: false
      interactive: true
    posix:
      shell: sh
      run: |
        # Set environment variables for the Container App
        azd env set AZURE_COSMOS_ENDPOINT "$AZURE_COSMOS_ENDPOINT"
      continueOnError: false
      interactive: true

Figyelje meg, hogy ez a konfiguráció a teljes TypeSpec-projektre hivatkozik.

A TypeSpec projekt gyökerében hozza létre a ./Dockerfile-t, amelyet az Azure Container Apps tárolójának létrehozásához használnak.

# Stage 1: Build stage
FROM node:20-alpine AS builder

WORKDIR /app

# Install TypeScript globally
RUN npm install -g typescript

# Copy package files first to leverage Docker layer caching
COPY package*.json ./

# Create the tsp-output/server directory structure
RUN mkdir -p tsp-output/server

# Copy server package.json 
COPY tsp-output/server/package.json ./tsp-output/server/

# Install build and dev dependencies
RUN npm i --force --no-package-lock
RUN cd tsp-output/server && npm install

# Copy the rest of the application code
COPY . .

# Build the TypeScript code
RUN cd tsp-output/server && tsc

#---------------------------------------------------------------

# Stage 2: Runtime stage
FROM node:20-alpine AS runtime

# Set NODE_ENV to production for better performance
ENV NODE_ENV=production

WORKDIR /app

# Copy only the server package files
COPY tsp-output/server/package.json ./

# Install only production dependencies
RUN npm install

# Copy all necessary files from the builder stage
# This includes the compiled JavaScript, any static assets, etc.
COPY --from=builder /app/tsp-output/server/dist ./dist

# Set default port and expose it
ENV PORT=3000
EXPOSE 3000

# Run the application
CMD ["node", "./dist/src/index.js"]

A TypeSpec projekt gyökerénél hozzon létre egy könyvtárat ./infra .

Hozzon létre egy ./infra/main.bicepparam fájlt, és másolja az alábbiakba az üzembe helyezéshez szükséges paraméterek meghatározásához:

using './main.bicep'

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

Ez a paramlista biztosítja az üzembe helyezéshez szükséges minimális paramétereket.

Hozzon létre egy ./infra/main.bicep fájlt, és másolja az alábbiakba a kiépítéshez és üzembe helyezéshez szükséges Azure-erőforrások meghatározásához:

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'
var partitionKey = '/id'

@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: [
              partitionKey
            ]
          }
        ]
      }
    ]
  }
}

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: 3000
    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/devcontainers/typescript-node'
        name: serviceName
        resources: {
          cpu: '0.25'
          memory: '.5Gi'
        }
        env: [
          {
            name: 'AZURE_COSMOS_ENDPOINT'
            secretRef: 'azure-cosmos-db-nosql-endpoint'
          }
          {
            name: 'AZURE_CLIENT_ID'
            secretRef: 'user-assigned-managed-identity-client-id'
          }
        ]
      }
    ]
  }
}

output AZURE_COSMOS_ENDPOINT string = cosmosDb.outputs.endpoint
output AZURE_COSMOS_DATABASE string = databaseName
output AZURE_COSMOS_CONTAINER string = containerName
output AZURE_COSMOS_PARTITION_KEY string = partitionKey

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerRegistry.outputs.loginServer
output AZURE_CONTAINER_REGISTRY_NAME string = containerRegistry.outputs.name

A KIMENETI változók lehetővé teszik a kiépített felhőerőforrások helyi fejlesztéssel való használatát.

Alkalmazás üzembe helyezése az Azure-ban

Ezt az alkalmazást az Azure Container Apps használatával telepítheti az Azure-ban:

A projekt gyökértermináljában hitelesítse magát az Azure Developer CLI-n:
```
azd auth login
```
Üzembe helyezés az Azure Container Appsben az Azure Developer CLI használatával:
```
azd up
```
Válaszoljon a következő kérdésekre a megadott válaszokkal:
- Adjon meg egy egyedi környezetnevet: tsp-server-js
- Válassza ki a használni kívánt Azure-előfizetést: válassza ki az előfizetését
- Válassza ki a használni kívánt Azure-helyet: válasszon egy Önhöz közeli helyet
- Válasszon egy használandó erőforráscsoportot: Válassza az Új erőforráscsoport létrehozása lehetőséget
- Adja meg az új erőforráscsoport nevét: fogadja el a megadott alapértelmezett értéket

Várjon, amíg az üzembe helyezés befejeződik. A válasz a következőhöz hasonló információkat tartalmaz:

Deploying services (azd deploy)

  (✓) Done: Deploying service api
  - Endpoint: https://container-app-123.ambitiouscliff-456.centralus.azurecontainerapps.io/


SUCCESS: Your up workflow to provision and deploy to Azure completed in 6 minutes 32 seconds.

Alkalmazás használata böngészőben

Az üzembe helyezést követően a következőt teheti:

A konzolon válassza ki az Endpoint URL-címet a böngészőben való megnyitásához.
Adja hozzá az útvonalat /.api-docs a végponthoz a Swagger UI felületének használatához.
A Kipróbálás funkcióval minden metóduson létrehozhat, olvashat, frissíthet és törölhet widgeteket az API-n keresztül.

Az alkalmazás növelése

Most, hogy a teljes folyamat teljes körűen működik, folytassa az API elkészítését:

Ismerje meg a TypeSpec nyelvet, hogy további API-kat és API-rétegfunkciókat adhasson hozzá a ./main.tsp.
Adjon hozzá további emittereket , és konfigurálja a paramétereket a ./tspconfig.yaml.
Ahogy további funkciókat ad hozzá a TypeSpec-fájlokhoz, a kiszolgálóprojekt forráskódjával támogatja ezeket a módosításokat.
Továbbra is használjon jelszó nélküli hitelesítést az Azure Identity használatával.

Erőforrások tisztítása

Ha végzett ezzel a rövid útmutatóval, eltávolíthatja az Azure-erőforrásokat:

azd down

Vagy törölje az erőforráscsoportot közvetlenül az Azure Portalról.

Következő lépések

Visszacsatolás

Hasznos volt ez az oldal?

Last updated on 2025-07-29