From 1ecd3f632c56a49c1cea6651e9f6e5145625d06a Mon Sep 17 00:00:00 2001 From: liangshiwei Date: Thu, 5 Sep 2024 16:47:49 +0800 Subject: [PATCH] Add BLOB Storing Google Provider document --- .../infrastructure/blob-storing/google.md | 70 +++++++++++++++++++ .../infrastructure/blob-storing/index.md | 1 + .../BlobStoring/Google/GoogleBlobProvider.cs | 5 ++ .../Google/GoogleBlobProviderConfiguration.cs | 9 +++ .../GoogleBlobProviderConfigurationNames.cs | 1 + .../Google/AbpBlobStoringGoogleTestModule.cs | 2 +- 6 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 docs/en/framework/infrastructure/blob-storing/google.md diff --git a/docs/en/framework/infrastructure/blob-storing/google.md b/docs/en/framework/infrastructure/blob-storing/google.md new file mode 100644 index 0000000000..a90152b4f0 --- /dev/null +++ b/docs/en/framework/infrastructure/blob-storing/google.md @@ -0,0 +1,70 @@ +# BLOB Storing Google Provider + +BLOB Storing Google Provider can store BLOBs in [Google Cloud Storage](https://cloud.google.com/storage). + +> Read the [BLOB Storing document](../blob-storing) to understand how to use the BLOB storing system. This document only covers how to configure containers to use a Google Cloud Storage as the storage provider. + +## Installation + +Use the ABP CLI to add [Volo.Abp.BlobStoring.Google](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Google) NuGet package to your project: + +* Install the [ABP CLI](../../../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.Google` package. +* Run `abp add-package Volo.Abp.BlobStoring.Google` command. + +If you want to do it manually, install the [Volo.Abp.BlobStoring.Google](https://www.nuget.org/packages/Volo.Abp.BlobStoring.Google) NuGet package to your project and add `[DependsOn(typeof(AbpBlobStoringGoogleModule))]` to the [ABP module](../../architecture/modularity/basics.md) class inside your project. + +## Configuration + +Configuration is done in the `ConfigureServices` method of your [module](../../architecture/modularity/basics.md) class, as explained in the [BLOB Storing document](../blob-storing). + +**Example: Configure to use the Google storage provider by default** + +````csharp +Configure(options => +{ + options.Containers.ConfigureDefault(container => + { + container.UseGoogle(google => + { + google.ClientEmail = "your coogle client email"; + google.ProjectId = "your coogle project id"; + google.PrivateKey = "your coogle private key"; + google.Scopes = "your coogle scopes"; + google.ContainerName = "your coogle container name"; + google.CreateContainerIfNotExists = true; + //google.UseApplicationDefaultCredentials = true; // If you want to use application default credentials + }); + }); +}); +```` + +> See the [BLOB Storing document](../blob-storing) to learn how to configure this provider for a specific container. + +### Options + +* **ClientEmail** (string): The client email of the Google service account. You can create a service account and get the client email. Please refer to Google documentation: https://cloud.google.com/iam/docs/service-account-overview +* **ProjectId** (string): The project ID of the Google service account. +* **PrivateKey** (string): The private key of the Google service account. You can create a service account and get the private key. Please refer to Google documentation: https://cloud.google.com/iam/docs/keys-create-delete +* **Scopes** (string): The scopes of the Google service account. +* **UseApplicationDefaultCredentials** (bool): If `true`, it uses the application default credentials(ADC). Default value is `false`. Please refer to Google documentation: https://cloud.google.com/docs/authentication/provide-credentials-adc +* **ContainerName** (string): You can specify the container name in Google. If this is not specified, it uses the name of the BLOB container defined with the `BlobContainerName` attribute (see the [BLOB storing document](../blob-storing)). Please note that Google has some **rules for naming containers**. A container name must be a valid DNS name, conforming to the [following naming rules](https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata#container-names): + * Container names must start or end with a letter or number, and can contain only letters, numbers, and the dash (-) character. + * Every dash (-) character must be immediately preceded and followed by a letter or number; consecutive dashes are not permitted in container names. + * All letters in a container name must be **lowercase**. + * Container names must be from **3** through **63** characters long. +* **CreateContainerIfNotExists** (bool): Default value is `false`, If a container does not exist in Google, `GoogleBlobProvider` will try to create it. + + +## Google Blob Name Calculator + +Google 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](../../architecture/multi-tenancy) is `null` (or multi-tenancy is disabled for the container - see the [BLOB Storing document](../blob-storing) 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 + +* `GoogleBlobProvider` is the main service that implements the Google BLOB storage provider, if you want to override/replace it via [dependency injection](../../fundamentals/dependency-injection.md) (don't replace `IBlobProvider` interface, but replace `GoogleBlobProvider` class). +* `IGoogleBlobNameCalculator` is used to calculate the full BLOB name (that is explained above). It is implemented by the `DefaultGoogleBlobNameCalculator` by default. diff --git a/docs/en/framework/infrastructure/blob-storing/index.md b/docs/en/framework/infrastructure/blob-storing/index.md index 61a05c65c0..f95a90e410 100644 --- a/docs/en/framework/infrastructure/blob-storing/index.md +++ b/docs/en/framework/infrastructure/blob-storing/index.md @@ -22,6 +22,7 @@ The ABP has already the following storage provider implementations: * [Aliyun](./aliyun.md): Stores BLOBs on the [Aliyun Storage Service](https://help.aliyun.com/product/31815.html). * [Minio](./minio.md): Stores BLOBs on the [MinIO Object storage](https://min.io/). * [Aws](./aws.md): Stores BLOBs on the [Amazon Simple Storage Service](https://aws.amazon.com/s3/). +* [Google](./google.md): Stores BLOBs on the [Google Cloud Storage](https://cloud.google.com/storage). 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](./custom-provider.md) and [contribute](../../../contribution) to the ABP. diff --git a/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProvider.cs b/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProvider.cs index 6f9b5c280e..cd5dc21d7f 100644 --- a/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProvider.cs +++ b/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProvider.cs @@ -141,6 +141,11 @@ public class GoogleBlobProvider : BlobProviderBase, ITransientDependency protected virtual async Task GetStorageClientClientAsync(BlobProviderArgs args) { var configuration = args.Configuration.GetGoogleConfiguration(); + if (configuration.UseApplicationDefaultCredentials) + { + return await StorageClient.CreateAsync(); + } + var googleCredential = GoogleCredential.FromServiceAccountCredential( new ServiceAccountCredential( new ServiceAccountCredential.Initializer(configuration.ClientEmail) diff --git a/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProviderConfiguration.cs b/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProviderConfiguration.cs index f00987b303..39db24f700 100644 --- a/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProviderConfiguration.cs +++ b/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProviderConfiguration.cs @@ -46,6 +46,15 @@ public class GoogleBlobProviderConfiguration set => _containerConfiguration.SetConfiguration(GoogleBlobProviderConfigurationNames.Scopes, value); } + /// + /// Use the application default credentials. https://cloud.google.com/docs/authentication/provide-credentials-adc + /// Default value: false. + /// + public bool UseApplicationDefaultCredentials { + get => _containerConfiguration.GetConfigurationOrDefault(GoogleBlobProviderConfigurationNames.UseApplicationDefaultCredentials, false); + set => _containerConfiguration.SetConfiguration(GoogleBlobProviderConfigurationNames.UseApplicationDefaultCredentials, value); + } + /// /// The name can only contain lowercase letters, numeric characters, dashes (-), underscores (_), and dots (.). Spaces are not allowed. Names containing dots require verification. /// Must start and end with a number or letter. diff --git a/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProviderConfigurationNames.cs b/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProviderConfigurationNames.cs index 0cfd10d129..c682c693c8 100644 --- a/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProviderConfigurationNames.cs +++ b/framework/src/Volo.Abp.BlobStoring.Google/Volo/Abp/BlobStoring/Google/GoogleBlobProviderConfigurationNames.cs @@ -6,6 +6,7 @@ public static class GoogleBlobProviderConfigurationNames public const string ClientEmail = "Google.ClientEmail"; public const string PrivateKey = "Google.PrivateKey"; public const string Scopes = "Google.Scopes"; + public const string UseApplicationDefaultCredentials = "Google.ApplicationDefaultCredentials"; public const string ContainerName = "Google.ContainerName"; public const string CreateContainerIfNotExists = "Google.CreateContainerIfNotExists"; } \ No newline at end of file diff --git a/framework/test/Volo.Abp.BlobStoring.Google.Tests/Volo/Abp/BlobStoring/Google/AbpBlobStoringGoogleTestModule.cs b/framework/test/Volo.Abp.BlobStoring.Google.Tests/Volo/Abp/BlobStoring/Google/AbpBlobStoringGoogleTestModule.cs index be2de91a38..36a100a191 100644 --- a/framework/test/Volo.Abp.BlobStoring.Google.Tests/Volo/Abp/BlobStoring/Google/AbpBlobStoringGoogleTestModule.cs +++ b/framework/test/Volo.Abp.BlobStoring.Google.Tests/Volo/Abp/BlobStoring/Google/AbpBlobStoringGoogleTestModule.cs @@ -53,7 +53,7 @@ public class AbpBlobStoringGoogleTestModule : AbpModule containerConfiguration.UseGoogle(google => { google.ClientEmail = _clientEmail; - google.ProjectId = _projectId = "wide-origin-296910"; + google.ProjectId = _projectId; google.PrivateKey = _privateKey; google.ContainerName = _randomContainerName; google.CreateContainerIfNotExists = true;