@abouroubi/azure-database 中文文档教程

Question

[特拉维斯形象]：https://api.travis-ci.org/nestjs/nest.svg?branch=master [特拉维斯网址]：https://travis-ci.org/nestjs/nest [linux-image]: https://img.shields.io/travis/nestjs/nest/master.svg?label=linux [linux-url]: https://travis-ci.org/nestjs/nest

一个渐进的 Node.js 构建框架高效且可扩展的服务器端应用程序。

<p align="center">

Description

Azure 数据库（表存储，Cosmos DB 等）Nest 框架 (node.js) 的模块

Tutorial

了解如何开始使用 NestJS 的 Azure 表存储

Before Installation

的表存储

1. Create a Storage account and resource (read more)
2. For Table Storage, In the Azure Portal, go to Dashboard > Storage > your-storage-account.
3. Note down the "Storage account name" and "Connection string" obtained at Access keys under Settings tab.

对于 Cosmos DB

1. Create a Cosmos DB account and resource (read more)
2. For Cosmos DB, In the Azure Portal, go to Dashboard > Azure Cosmos DB > your-cosmos-db-account.
3. Note down the "URI" and "Primary Key" obtained at Keys under Settings tab.

Installation

$ npm i --save @nestjs/azure-database

Usage

For Azure Table Storage support

1. Create or update your existing .env file with the following content:

AZURE_STORAGE_CONNECTION_STRING=

2. 重要：请务必将您的 .env 文件添加到您的 .gitignore 中！ .env 文件不得在 Git 上进行版本控制。

3. 确保包含对主文件的以下调用：

if (process.env.NODE_ENV !== 'production') require('dotenv').config();

必须在任何其他导入之前添加此行！

Example

Prepare your entity

0. Create a new feature module, eg. with the nest CLI:

$ nest generate module contact

1. Create a Data Transfer Object (DTO) inside a file named contact.dto.ts:

export class ContactDTO {
  name: string;
  message: string;
}

2. Create a file called contact.entity.ts and describe the entity model using the provided decorators:

• @EntityPartitionKey(value: string)：表示实体的PartitionKey（必填）。

• @EntityRowKey(value: string)：表示实体的RowKey（必填）。

• @EntityInt32(value?: string)：用于带符号的 32 位整数值。

• @EntityInt64(value?: string)：用于带符号的 64 位整数值。

• @EntityBinary(value?: string)：用于二进制（blob）数据。

• @EntityBoolean(value?: string)：对于 true 或 false 值。

• @EntityString(value?: string)：用于字符数据。

• @EntityDouble(value?: string)：用于 15 位精度的浮点数。

• @EntityDateTime(value?: string)：一天中的时间。

例如，以下实体的形状：

import { EntityPartitionKey, EntityRowKey, EntityString } from '@nestjs/azure-database';

@EntityPartitionKey('ContactID')
@EntityRowKey('ContactName')
export class Contact {
  @EntityString() name: string;
  @EntityString() message: string;
}

将自动转换为：

{
  "PartitionKey": { "_": "ContactID", "$": "Edm.String" },
  "RowKey": { "_": "ContactName", "$": "Edm.String" },
  "name": { "_": undefined, "$": "Edm.String" },
  "message": { "_": undefined, "$": "Edm.String" }
}

注意：提供的实体类型注释表示实体数据模型类型。

3. Import the AzureTableStorageModule inside your Nest feature module contact.module.ts:

import { Module } from '@nestjs/common';
import { AzureTableStorageModule } from '@nestjs/azure-database';
import { ContactController } from './contact.controller';
import { ContactService } from './contact.service';
import { Contact } from './contact.entity';

@Module({
  imports: [AzureTableStorageModule.forFeature(Contact)],
  providers: [ContactService],
  controllers: [ContactController],
})
export class ContactModule {}

您可以选择传入以下参数：

AzureTableStorageModule.forFeature(Contact, {
  table: 'AnotherTableName',
  createTableIfNotExists: true,
});

• table: string: The name of the table. If not provided, the name of the Contact entity will be used as a table name
• createTableIfNotExists: boolean: Whether to automatically create the table if it doesn't exists or not:
• If true the table will be created during the startup of the app.
• If false the table will not be created. You will have to create the table by yourself before querying it!

CRUD operations

0. Create a service that will abstract the CRUD operations:

$ nest generate service contact

1. Use the @InjectRepository(Contact) to get an instance of the Azure Repository for the entity definition created earlier:

import { Injectable } from '@nestjs/common';
import { Repository, InjectRepository } from '@nestjs/azure-database';
import { Contact } from './contact.entity';

@Injectable()
export class ContactService {
  constructor(
    @InjectRepository(Contact)
    private readonly contactRepository: Repository<Contact>,
  ) {}
}

AzureTableStorageRepository 提供了几个公共 API 和接口来管理各种 CRUD 操作：

CREATE

create(entity: T, rowKeyValue?: string): Promise ;：创建一个新实体。

  @Post()
  async create(contact: Contact, rowKeyValue: string): Promise<Contact> {
    //if rowKeyValue is null, rowKeyValue will generate a UUID
    return this.contactRepository.create(contact, rowKeyValue)
  }

READ

find(rowKey: string, entity: Partial): Promise：使用其 RowKey 查找一个实体。

  @Get(':rowKey')
  async getContact(@Param('rowKey') rowKey) {
    try {
      return await this.contactRepository.find(rowKey, new Contact());
    } catch (error) {
      // Entity not found
      throw new UnprocessableEntityException(error);
    }
  }

findAll(tableQuery?: azure.TableQuery, currentToken?: azure.TableService.TableContinuationToken): Promise>：查找与给定查询匹配的所有实体（如果没有查询则返回所有实体假如）。

  @Get()
  async getAllContacts() {
    return await this.contactRepository.findAll();
  }

UPDATE

update(rowKey: string, entity: Partial): Promise：更新一个实体。 它进行部分更新。

  @Put(':rowKey')
  async saveContact(@Param('rowKey') rowKey, @Body() contactData: ContactDTO) {
    try {
      const contactEntity = new Contact();
      // Disclaimer: Assign only the properties you are expecting!
      Object.assign(contactEntity, contactData);

      return await this.contactRepository.update(rowKey, contactEntity);
    } catch (error) {
      throw new UnprocessableEntityException(error);
    }
  }
  @Patch(':rowKey')
  async updateContactDetails(@Param('rowKey') rowKey, @Body() contactData: Partial<ContactDTO>) {
    try {
      const contactEntity = new Contact();
      // Disclaimer: Assign only the properties you are expecting!
      Object.assign(contactEntity, contactData);

      return await this.contactRepository.update(rowKey, contactEntity);
    } catch (error) {
      throw new UnprocessableEntityException(error);
    }
  }

DELETE

delete(rowKey: string, entity: T): Promise：从数据库中删除一个实体。

  @Delete(':rowKey')
  async deleteDelete(@Param('rowKey') rowKey) {
    try {
      const response = await this.contactRepository.delete(rowKey, new Contact());

      if (response.statusCode === 204) {
        return null;
      } else {
        throw new UnprocessableEntityException(response);
      }
    } catch (error) {
      throw new UnprocessableEntityException(error);
    }
  }

For Azure Cosmos DB support

1. Create or update your existing .env file with the following content:

AZURE_COSMOS_DB_NAME=
AZURE_COSMOS_DB_ENDPOINT=
AZURE_COSMOS_DB_KEY=

2. 重要提示：确保将您的 .env 文件添加到您的 .gitignore！ .env 文件不得在 Git 上进行版本控制。

3. 确保包含对主文件的以下调用：

if (process.env.NODE_ENV !== 'production') require('dotenv').config();

必须在任何其他导入之前添加此行！

Example

注意：查看 示例文件夹

Prepare your entity

0. Create a new feature module, eg. with the nest CLI:

$ nest generate module event

1. Create a Data Transfer Object (DTO) inside a file named event.dto.ts:

export class EventDTO {
  name: string;
  type: string;
  date: Date;
  location: Point;
}

2. Create a file called event.entity.ts and describe the entity model using the provided decorators:

• 中包含的 CosmosDB 示例项目@CosmosPartitionKey(value: string)：表示实体的PartitionKey（必填）。

• @CosmosDateTime(value?: string)：用于日期时间值。

例如，以下实体的形状：

import { CosmosPartitionKey, CosmosDateTime, Point } from '@nestjs/azure-database';

@CosmosPartitionKey('type')
export class Event {
  id?: string;
  type: string;
  @CosmosDateTime() createdAt: Date;
  location: Point;
}

将自动转换为：

{
  "type": "Meetup",
  "createdAt": "2019-11-15T17:05:25.427Z",
  "position": {
    "type": "Point",
    "coordinates": [2.3522, 48.8566]
  }
}

3. Import the AzureCosmosDbModule inside your Nest feature module event.module.ts:

import { Module } from '@nestjs/common';
import { AzureCosmosDbModule } from '@nestjs/azure-database';
import { EventController } from './event.controller';
import { EventService } from './event.service';
import { Event } from './event.entity';

@Module({
  imports: [
    AzureCosmosDbModule.forRoot({
      dbName: process.env.AZURE_COSMOS_DB_NAME,
      endpoint: process.env.AZURE_COSMOS_DB_ENDPOINT,
      key: process.env.AZURE_COSMOS_DB_KEY,
    }),
    AzureCosmosDbModule.forFeature([{ dto: Event }]),
  ],
  providers: [EventService],
  controllers: [EventController],
})
export class EventModule {}

CRUD operations

0. Create a service that will abstract the CRUD operations:

$ nest generate service event

1. Use the @InjectModel(Event) to get an instance of the Azure Cosmos DB Container for the entity definition created earlier:

import { Injectable } from '@nestjs/common';
import { InjectModel } from '@nestjs/azure-database';
import { Event } from './event.entity';

@Injectable()
export class EventService {
  constructor(
    @InjectModel(Event)
    private readonly eventContainer,
  ) {}
}

Azure Cosmos DB Container 提供了几个公共 API 和接口来管理各种 CRUD 操作：

CREATE

create(entity: T ): Promise：创建一个新实体。

  @Post()
  async create(event: Event): Promise<Event> {
      return this.eventContainer.items.create(event)
  }

READ

query(query: string | SqlQuerySpec, options?: FeedOptions): QueryIterator：运行 SQL 查询以查找文档。

  @Get(':id')
  async getContact(@Param('id') id) {
    try {
       const querySpec = {
           query: "SELECT * FROM root r WHERE r.id=@id",
           parameters: [
             {
               name: "@id",
               value: id
             }
           ]
         };
        const { resources } = await this.eventContainer.items.query<Event>(querySpec).fetchAll()
         return resources
    } catch (error) {
      // Entity not found
      throw new UnprocessableEntityException(error);
    }
  }

UPDATE

read(options?: RequestOptions): Promise>：获取文档。 replace(body: T, options?: RequestOptions): Promise>：更新文档。

  @Put(':id')
  async saveEvent(@Param('id') id, @Body() eventData: EventDTO) {
    try {
      const { resource: item } = await this.eventContainer.item<Event>(id, 'type').read()

      // Disclaimer: Assign only the properties you are expecting!
      Object.assign(item, eventData);

      const { resource: replaced } = await this.eventContainer
       .item(id, 'type')
       .replace<Event>(item)
      return replaced
    } catch (error) {
      throw new UnprocessableEntityException(error);
    }
  }

DELETE

delete(options?: RequestOptions): Promise>：从数据库中删除一个实体。

  @Delete(':id')
  async deleteEvent(@Param('id') id) {
    try {
      const { resource: deleted } = await this.eventContainer
       .item(id, 'type')
       .delete<Event>()

      return deleted;
    } catch (error) {
      throw new UnprocessableEntityException(error);
    }
  }

Support

Nest 是 MIT 许可的开源项目。 由于赞助商和惊人支持者的支持，它可以成长。 如果您想加入他们，请在此处阅读更多信息。

Stay in touch

• Author - Wassim Chegham
• Website - https://wassim.dev
• Twitter - @manekinekko

License

Nest 已获得 MIT 许可。