diff --git a/docs/en/Blob-Storing-Aws.md b/docs/en/Blob-Storing-Aws.md new file mode 100644 index 0000000000..a2ac8309ca --- /dev/null +++ b/docs/en/Blob-Storing-Aws.md @@ -0,0 +1,81 @@ +# BLOB Storing Aws Provider + +BLOB Storing Aws Provider can store BLOBs in [Amazon Simple Storage Service](https://aws.amazon.com/s3/). + +> Read the [BLOB Storing document](Blob-Storing.md) to understand how to use the BLOB storing system. This document only covers how to configure containers to use a Aws BLOB as the storage provider. + +## Installation + +Use the ABP CLI to add [Volo.Abp.BlobStoring.Aws](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Aws) NuGet package to your project: + +* Install the [ABP CLI](https://docs.abp.io/en/abp/latest/CLI) if you haven't installed before. +* Open a command line (terminal) in the directory of the `.csproj` file you want to add the `Volo.Abp.BlobStoring.Aws` package. +* Run `abp add-package Volo.Abp.BlobStoring.Aws` command. + +If you want to do it manually, install the [Volo.Abp.BlobStoring.Aws](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Aws) NuGet package to your project and add `[DependsOn(typeof(AbpBlobStoringAwsModule))]` to the [ABP module](Module-Development-Basics.md) class inside your project. + +## Configuration + +Configuration is done in the `ConfigureServices` method of your [module](Module-Development-Basics.md) class, as explained in the [BLOB Storing document](Blob-Storing.md). + +**Example: Configure to use the Aws storage provider by default** + +````csharp +Configure(options => +{ + options.Containerscontainer.UseAws(Aws => + { + Aws.AccessKeyId = "your Aws access key id"; + Aws.SecretAccessKey = "your Aws access key secret"; + Aws.UseCredentials = "set true to use credentials"; + Aws.UseTemporaryCredentials = "set true to use temporary credentials"; + Aws.UseTemporaryFederatedCredentials = "set true to use temporary federated credentials"; + Aws.ProfileName = "the name of the profile to get credentials from"; + Aws.ProfilesLocation = "the path to the aws credentials file to look at"; + Aws.Region = "the system name of the service"; + Aws.Name = "the name of the federated user"; + Aws.Policy = "policy"; + Aws.DurationSeconds = "expiration date"; + Aws.ContainerName = "your Aws container name"; + Aws.CreateContainerIfNotExists = false; + }); +}); +```` + +> See the [BLOB Storing document](Blob-Storing.md) to learn how to configure this provider for a specific container. + +### Options + +* **AccessKeyId** (string): AWS Access Key ID. +* **SecretAccessKey** (string): AWS Secret Access Key. +* **UseCredentials** (bool): Use [credentials](https://docs.aws.amazon.com/AmazonS3/latest/dev/AuthUsingAcctOrUserCredentials.html) to access AWS services,default : `false`. +* **UseTemporaryCredentials** (bool): Use [temporary credentials](https://docs.aws.amazon.com/AmazonS3/latest/dev/AuthUsingTempSessionToken.html) to access AWS services,default : `false`. +* **UseTemporaryFederatedCredentials** (bool): Use [federated user temporary credentials](https://docs.aws.amazon.com/AmazonS3/latest/dev/AuthUsingTempFederationToken.html) to access AWS services, default : `false`. +* **ProfileName** (string): The [name of the profile]((https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-creds.html)) to get credentials from. +* **ProfilesLocation** (string): The path to the aws credentials file to look at. +* **Region** (string): The system name of the service. +* **Policy** (string): An IAM policy in JSON format that you want to use as an inline session policy. +* **DurationSeconds** (int): Validity period(s) of a temporary access certificate,minimum is 900 and the maximum is 3600. **note**: Using subaccounts operated OSS,if the value is 0. +* **ContainerName** (string): You can specify the container name in Aws. If this is not specified, it uses the name of the BLOB container defined with the `BlogContainerName` attribute (see the [BLOB storing document](Blob-Storing.md)). Please note that Aws has some **rules for naming containers**. A container name must be a valid DNS name, conforming to the [following naming rules](https://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html): + * Bucket names must be between **3** and **63** characters long. + * Bucket names can consist only of **lowercase** letters, numbers, dots (.), and hyphens (-). + * Bucket names must begin and end with a letter or number. + * Bucket names must not be formatted as an IP address (for example, 192.168.5.4). + * Bucket names can't begin with **xn--** (for buckets created after February 2020). + * Bucket names must be unique within a partition. + * Buckets used with Amazon S3 Transfer Acceleration can't have dots (.) in their names. For more information about transfer acceleration, see Amazon S3 Transfer Acceleration. +* **CreateContainerIfNotExists** (bool): Default value is `false`, If a container does not exist in Aws, `AwsBlobProvider` will try to create it. + +## Aws Blob Name Calculator + +Aws Blob Provider organizes BLOB name and implements some conventions. The full name of a BLOB is determined by the following rules by default: + +* Appends `host` string if [current tenant](Multi-Tenancy.md) is `null` (or multi-tenancy is disabled for the container - see the [BLOB Storing document](Blob-Storing.md) to learn how to disable multi-tenancy for a container). +* Appends `tenants/` string if current tenant is not `null`. +* Appends the BLOB name. + +## Other Services + +* `AwsBlobProvider` is the main service that implements the Aws BLOB storage provider, if you want to override/replace it via [dependency injection](Dependency-Injection.md) (don't replace `IBlobProvider` interface, but replace `AwsBlobProvider` class). +* `IAwsBlobNameCalculator` is used to calculate the full BLOB name (that is explained above). It is implemented by the `DefaultAwsBlobNameCalculator` by default. +* `IAmazonS3ClientFactory` is used create OSS client. It is implemented by the `DefaultAmazonS3ClientFactory` by default. You can override/replace it,if you want customize. \ No newline at end of file diff --git a/docs/en/Blob-Storing.md b/docs/en/Blob-Storing.md index 444766b4bb..23b4f80560 100644 --- a/docs/en/Blob-Storing.md +++ b/docs/en/Blob-Storing.md @@ -19,8 +19,9 @@ The ABP Framework has already the following storage provider implementations; * [File System](Blob-Storing-File-System.md): Stores BLOBs in a folder of the local file system, as standard files. * [Database](Blob-Storing-Database.md): Stores BLOBs in a database. * [Azure](Blob-Storing-Azure.md): Stores BLOBs on the [Azure BLOB storage](https://azure.microsoft.com/en-us/services/storage/blobs/). -* [Aliyun](Blob-Storing-Aliyun.md): Stores BLOBs on the [Aliyun Blob storage](https://help.aliyun.com/product/31815.html). +* [Aliyun](Blob-Storing-Aliyun.md): Stores BLOBs on the [Aliyun Storage Service](https://help.aliyun.com/product/31815.html). * [Ninio](Blob-Storing-Minio.md): Stores BLOBs on the [MinIO Object storage](https://min.io/). +* [Aws](Blob-Storing-Aws.md): Stores BLOBs on the[Amazon Simple Storage Service](https://min.io/). More providers will be implemented by the time. You can [request](https://github.com/abpframework/abp/issues/new) it for your favorite provider or [create it yourself](Blob-Storing-Custom-Provider.md) and [contribute](Contribution/Index.md) to the ABP Framework. diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 8952e3c997..54cd595fe4 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -224,6 +224,10 @@ "text": "Minio Provider", "path": "Blob-Storing-Minio.md" }, + { + "text": "Minio Provider", + "path": "Blob-Storing-Aws.md" + }, { "text": "Create a Custom Provider", "path": "Blob-Storing-Custom-Provider.md" diff --git a/docs/zh-Hans/Blob-Storing-Aws.md b/docs/zh-Hans/Blob-Storing-Aws.md new file mode 100644 index 0000000000..6d50acce9d --- /dev/null +++ b/docs/zh-Hans/Blob-Storing-Aws.md @@ -0,0 +1,81 @@ +# BLOB Storing Aws提供程序 + +BLOB存储Aws提供程序可以将BLOB存储在[Amazon Simple Storage Service](https://aws.amazon.com/cn/s3/)中. + +> 阅读[BLOB存储文档](Blob-Storing.md)了解如何使用BLOB存储系统. 本文档仅介绍如何为容器配置Aws提供程序. + +## 安装 + +使用ABP CLI添加[Volo.Abp.BlobStoring.Aws](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Aws)NuGet包到你的项目: + +* 安装 [ABP CLI](https://docs.abp.io/en/abp/latest/CLI), 如果你还没有安装. +* 在要添加 `Volo.Abp.BlobStoring.Aws` 包的 `.csproj` 文件目录打开命令行. +* 运行 `Volo.Abp.BlobStoring.Aws` 命令. + +如果要手动安装,在你的项目中安装 `Volo.Abp.BlobStoring.Aws` NuGet包然后将`[DependsOn(typeof(AbpBlobStoringAwsModule))]`添加到项目内的[ABP模块](Module-Development-Basics.md)类中. + +## 配置 + +如同[BLOB存储文档](Blob-Storing.md)所述,配置是在[模块](Module-Development-Basics.md)类的 `ConfigureServices` 方法完成的. + +**示例: 配置为默认使用Aws存储提供程序** + +````csharp +Configure(options => +{ + options.Containerscontainer.UseAws(Aws => + { + Aws.AccessKeyId = "your Aws access key id"; + Aws.SecretAccessKey = "your Aws access key secret"; + Aws.UseCredentials = "set true to use credentials"; + Aws.UseTemporaryCredentials = "set true to use temporary credentials"; + Aws.UseTemporaryFederatedCredentials = "set true to use temporary federated credentials"; + Aws.ProfileName = "the name of the profile to get credentials from"; + Aws.ProfilesLocation = "the path to the aws credentials file to look at"; + Aws.Region = "the system name of the service"; + Aws.Name = "the name of the federated user"; + Aws.Policy = "policy"; + Aws.DurationSeconds = "expiration date"; + Aws.ContainerName = "your Aws container name"; + Aws.CreateContainerIfNotExists = false; + }); +}); +```` + +> 参阅[BLOB存储文档](Blob-Storing.md) 学习如何为指定容器配置提供程序. + +### 选项 + +* **AccessKeyId** (string): AWS Access Key ID. +* **SecretAccessKey** (string): AWS Secret Access Key. +* **UseCredentials** (bool): 使用[本地凭证](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/dev/AuthUsingAcctOrUserCredentials.html)访问AWS服务,默认: `false`. +* **UseTemporaryCredentials** (bool): 使用[临时凭证](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/dev/AuthUsingTempSessionToken.html)访问AWS服务,默认: `false`. +* **UseTemporaryFederatedCredentials** (bool): 使用[联合身份用户临时凭证](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/dev/AuthUsingTempFederationToken.html)访问AWS服务, 默认: `false`. +* **ProfileName** (string): [本地凭证配置文件](https://docs.aws.amazon.com/zh_cn/sdk-for-net/v3/developer-guide/net-dg-config-creds.html)名称. +* **ProfilesLocation** (string): 本地配置文件位置. +* **Region** (string): 服务的地区名称. +* **Policy** (string): JSON格式的IAM策略. +* **DurationSeconds** (int): 设置临时访问凭证的有效期,单位是s,最小为900,最大为129600. +* **ContainerName** (string): 你可以在Aws中指定容器名称. 如果没有指定它将使用 `BlogContainerName` 属性定义的BLOB容器的名称(请参阅[BLOB存储文档](Blob-Storing.md)). 请注意Aws有一些**命名容器的规则**,容器名称必须是有效的DNS名称,[符合以下命名规则](https://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html): + * Bucket名称必须介于 3 到 63 个字符之间. + * Bucket名称只能由小写字母、数字、句点 (.) 和连字符 (-) 组成. + * Bucket名称必须以字母或数字开头和结尾. + * Bucket名称不能是ip (例如, 192.168.5.4). + * Bucket名称不能以 **xn--** 开头, (对于2020年2月以后创建的 Bucket). + * Bucket名称在分区中必须唯一 . + * Bucket 与 Amazon S3 Transfer Acceleration 一起使用时名称中不能有句点 (.). +* **CreateContainerIfNotExists** (bool): 默认值为 `false`, 如果Aws中不存在容器, `AwsBlobProvider` 将尝试创建它. + +## Aws BLOB 名称计算器 + +Aws BLOB提供程序组织BLOB名称并实现一些约定. 默认情况下BLOB的全名由以下规则确定: + +* 如果当前租户为 `null`(或容器禁用多租户 - 请参阅[BLOB存储文档](Blob-Storing.md) 了解如何禁用容器的多租户),则追加 `host` 字符串. +* 如果当前租户不为 `null`,则追加 `tenants/` 字符串. +* 追加 BLOB 名称. + +## 其他服务 + +* `AwsBlobProvider` 是实现Aws BLOB存储提供程序的主要服务,如果你想要通过[依赖注入](Dependency-Injection.md)覆盖/替换它(不要替换 `IBlobProvider` 接口,而是替换 `AwsBlobProvider` 类). +* `IAwsBlobNameCalculator` 服务用于计算文件路径. 默认实现是 `DefaultAwsBlobNameCalculator`. 如果你想自定义文件路径计算,可以替换/覆盖它. +* `IAmazonS3ClientFactory` 服务用于生成AWS S3客户端. 默认实现是 `DefaultAmazonS3ClientFactory` . 如果你想自定义AWS S3客户端生成,可以替换/覆盖它. diff --git a/docs/zh-Hans/Blob-Storing-Minio.md b/docs/zh-Hans/Blob-Storing-Minio.md index f7c0b25771..a2974e0843 100644 --- a/docs/zh-Hans/Blob-Storing-Minio.md +++ b/docs/zh-Hans/Blob-Storing-Minio.md @@ -41,13 +41,13 @@ Configure(options => * **AccessKey** (string): Access key是唯一标识你的账户的用户ID, * **SecretKey** (string): Access key是唯一标识你的账户的用户ID * **BucketName** (string):你可以指定bucket名称,如果没有指定,将使用 `BlogContainerName` 属性定义的BLOB容器的名称(查阅[BLOB storing document](Blob-Storing.md)),MinIO完全兼容S3标准,所以有一些 **bucket命名规则**,必须符合[规则](https://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html): - * Bucket名字必须 **3** 到 **63** 字符长度. - * Bucket名字必须是 **小写** 的字母,数字,点号(.), 横杠 (-), - * Bucket名字必须是以数字和字母开头和结尾, - * Bucket名字不能是ip (例如, 192.168.5.4), - * Bucket名字不能以 **xn--** 开头, (2020年2月以后创建), - * Bucket名字必须区块唯一 - * Buckets如果使用Amazon S3加速传输名字不能有点号(.), + * Bucket名称必须介于 3 到 63 个字符之间. + * Bucket名称只能由小写字母、数字、句点 (.) 和连字符 (-) 组成. + * Bucket名称必须以字母或数字开头和结尾. + * Bucket名称不能是ip (例如, 192.168.5.4). + * Bucket名称不能以 **xn--** 开头, (对于2020年2月以后创建的 Bucket). + * Bucket名称在分区中必须唯一 . + * Bucket 与 Amazon S3 Transfer Acceleration 一起使用时名称中不能有句点 (.). * **WithSSL** (bool): 默认 `false`,代表使用HTTPS, * **CreateContainerIfNotExists** (bool): 默认 `false`,如果不存在bucket, `MinioBlobProvider` 将会创建一个, diff --git a/docs/zh-Hans/Blob-Storing.md b/docs/zh-Hans/Blob-Storing.md index ba166d6aeb..99688ca47a 100644 --- a/docs/zh-Hans/Blob-Storing.md +++ b/docs/zh-Hans/Blob-Storing.md @@ -19,8 +19,9 @@ ABP框架已经有以下存储提供程序的实现; * [File System](Blob-Storing-File-System.md):将BLOB作为标准文件存储在本地文件系统的文件夹中. * [Database](Blob-Storing-Database.md): 将BLOB存储在数据库中. * [Azure](Blob-Storing-Azure.md): 将BLOG存储在 [Azure BLOB storage](https://azure.microsoft.com/en-us/services/storage/blobs/)中. -* [Aliyun](Blob-Storing-Aliyun.md): 将BLOB存储在[Aliyun Blob storage](https://help.aliyun.com/product/31815.html)中. +* [Aliyun](Blob-Storing-Aliyun.md): 将BLOB存储在[Aliyun Storage Service](https://help.aliyun.com/product/31815.html)中. * [Ninio](Blob-Storing-Minio.md): 将BLOB存储在[MinIO Object storage](https://min.io/)中. +* [Aws](Blob-Storing-Aws.md): 将BLOB存储在[Amazon Simple Storage Service](https://min.io/)中. 以后会实现更多的提供程序,你可以为自己喜欢的提供程序创建[请求](https://github.com/abpframework/abp/issues/new),或者你也可以[自己实现](Blob-Storing-Custom-Provider.md)它并[贡献](Contribution/Index.md)到ABP框架. diff --git a/docs/zh-Hans/docs-nav.json b/docs/zh-Hans/docs-nav.json index 732f6c08f4..cae14bdae2 100644 --- a/docs/zh-Hans/docs-nav.json +++ b/docs/zh-Hans/docs-nav.json @@ -218,6 +218,10 @@ "text": "Minio提供程序", "path": "Blob-Storing-Minio.md" }, + { + "text": "AWS提供程序", + "path": "Blob-Storing-Aws.md" + }, { "text": "创建自定义提供程序", "path": "Blob-Storing-Custom-Provider.md" diff --git a/framework/src/Volo.Abp.BlobStoring.Aws/Volo/Abp/BlobStoring/Aws/DefaultAmazonS3ClientFactory.cs b/framework/src/Volo.Abp.BlobStoring.Aws/Volo/Abp/BlobStoring/Aws/DefaultAmazonS3ClientFactory.cs index 78ef55aebb..739818c0d9 100644 --- a/framework/src/Volo.Abp.BlobStoring.Aws/Volo/Abp/BlobStoring/Aws/DefaultAmazonS3ClientFactory.cs +++ b/framework/src/Volo.Abp.BlobStoring.Aws/Volo/Abp/BlobStoring/Aws/DefaultAmazonS3ClientFactory.cs @@ -37,7 +37,7 @@ namespace Volo.Abp.BlobStoring.Aws var awsCredentials = GetAwsCredentials(configuration); return awsCredentials == null ? new AmazonS3Client(region) - : new AmazonS3Client(GetAwsCredentials(configuration), region); + : new AmazonS3Client(awsCredentials, region); } if (configuration.UseTemporaryCredentials)