提供者

¥Providers

某些 plugins 可以通过安装和配置附加 providers 来扩展。

¥Certain plugins can be extended via the installation and configuration of additional providers.

提供者为插件的核心功能添加了扩展，例如将媒体文件上传到 AWS S3 而不是本地服务器，或者使用 Amazon SES 代替 Sendmail 发送电子邮件。

¥Providers add an extension to the core capabilities of the plugin, for example to upload media files to AWS S3 instead of the local server, or using Amazon SES for emails instead of Sendmail.

注意

目前只有上传和电子邮件插件被设计为与提供者一起使用。

¥Only the Upload and Email plugins are currently designed to work with providers.

对于相关插件，既有由 Strapi 维护的官方提供程序（可通过市场发现），也有许多社区维护的提供程序可通过 npm 获取。

¥For the relevant plugins, there are both official providers maintained by Strapi — discoverable via the Marketplace — and many community maintained providers available via npm.

可以将提供程序配置为 private，以确保对资源 URL 进行签名以实现安全访问。

¥A provider can be configured to be private to ensure asset URLs will be signed for secure access.

安装提供程序

¥Installing providers

可以使用 npm 或 yarn 使用以下格式 @strapi/provider-<plugin>-<provider> --save 安装新的提供程序。

¥New providers can be installed using npm or yarn using the following format @strapi/provider-<plugin>-<provider> --save.

例如：

¥For example:

yarn
npm

#Install the AWS S3 provider for the Upload plugin

yarn add @strapi/provider-upload-aws-s3

# Install the Sendgrid provider for the Email plugin
yarn add @strapi/provider-email-sendgrid --save

#Install the AWS S3 provider for the Upload plugin

npm install @strapi/provider-upload-aws-s3 --save

# Install the Sendgrid provider for the Email plugin
npm install @strapi/provider-email-sendgrid --save

配置提供者

¥Configuring providers

新安装的提供程序在 ./config/plugins.js 文件中启用和配置。如果该文件不存在，则必须创建它。

¥Newly installed providers are enabled and configured in the ./config/plugins.js file. If this file does not exist you must create it.

每个提供者都有不同的可用配置设置。查看市场或 npm 中该提供者的相应条目以了解更多信息。

¥Each provider will have different configuration settings available. Review the respective entry for that provider in the Marketplace or npm to learn more.

以下是上传和电子邮件插件的示例配置。

¥Below are example configurations for the Upload and Email plugins.

Upload
Email

JavaScript
TypeScript

./config/plugins.js

module.exports = ({ env }) => ({
  // ...
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        baseUrl: env('CDN_URL'),
        rootPath: env('CDN_ROOT_PATH'),
        s3Options: {
          credentials: {
            accessKeyId: env('AWS_ACCESS_KEY_ID'),
            secretAccessKey: env('AWS_ACCESS_SECRET'),
          },
          region: env('AWS_REGION'),
          params: {
            ACL: env('AWS_ACL', 'public-read'),
            signedUrlExpires: env('AWS_SIGNED_URL_EXPIRES', 15 * 60),
            Bucket: env('AWS_BUCKET'),
          },
        },
      },
      actionOptions: {
        upload: {},
        uploadStream: {},
        delete: {},
      },
    },
  },
  // ...
});

./config/plugins.ts

export default ({ env }) => ({
  // ...
  upload: {
    config: {
      provider: 'aws-s3', // For community providers pass the full package name (e.g. provider: 'strapi-provider-upload-google-cloud-storage')
      providerOptions: {
        accessKeyId: env('AWS_ACCESS_KEY_ID'),
        secretAccessKey: env('AWS_ACCESS_SECRET'),
        region: env('AWS_REGION'),
        params: {
          ACL: env('AWS_ACL', 'public-read'), // 'private' if you want to make the uploaded files private
          Bucket: env('AWS_BUCKET'),
        },
      },
    },
  },
  // ...
});

注意

Strapi 有一个默认的 security 中间件，它有一个非常严格的 contentSecurityPolicy，限制仅加载图片和媒体到 "'self'"，请参阅提供者页面或中间件文档上的示例配置以了解更多信息。

¥Strapi has a default security middleware that has a very strict contentSecurityPolicy that limits loading images and media to "'self'" only, see the example configuration on the provider page or the middleware documentation for more information.

JavaScript
TypeScript

./config/plugins.js

module.exports = ({ env }) => ({
  // ...
  email: {
    config: {
      provider: 'sendgrid', // For community providers pass the full package name (e.g. provider: 'strapi-provider-email-mandrill')
      providerOptions: {
        apiKey: env('SENDGRID_API_KEY'),
      },
      settings: {
        defaultFrom: 'juliasedefdjian@strapi.io',
        defaultReplyTo: 'juliasedefdjian@strapi.io',
        testAddress: 'juliasedefdjian@strapi.io',
      },
    },
  },
  // ...
});

./config/plugins.ts

export default ({ env }) => ({
  // ...
  email: {
    config: {
      provider: 'sendgrid', // For community providers pass the full package name (e.g. provider: 'strapi-provider-email-mandrill')
      providerOptions: {
        apiKey: env('SENDGRID_API_KEY'),
      },
      settings: {
        defaultFrom: 'juliasedefdjian@strapi.io',
        defaultReplyTo: 'juliasedefdjian@strapi.io',
        testAddress: 'juliasedefdjian@strapi.io',
      },
    },
  },
  // ...
});

注意

当每个环境使用不同的提供程序时，请在 ./config/env/${yourEnvironment}/plugins.js 中指定正确的配置（请参阅环境）。

¥When using a different provider per environment, specify the correct configuration in ./config/env/${yourEnvironment}/plugins.js (See Environments).
一次只有一个电子邮件提供者处于活动状态。如果 Strapi 未选择电子邮件提供者设置，请验证 plugins.js 文件是否位于正确的文件夹中。

¥Only one email provider will be active at a time. If the email provider setting isn't picked up by Strapi, verify the plugins.js file is in the correct folder.
使用在 Strapi 设置期间创建的两个电子邮件模板测试新电子邮件提供者时，模板上的发送者电子邮件默认为 no-reply@strapi.io，需要根据你的电子邮件提供者进行更新，否则将无法通过测试（请参阅本地配置模板）。

¥When testing the new email provider with those two email templates created during strapi setup, the shipper email on the template defaults to no-reply@strapi.io and needs to be updated according to your email provider, otherwise it will fail the test (See Configure templates locally).

每个环境的配置

¥Configuration per environment

配置提供程序时，你可能希望根据 NODE_ENV 环境变量更改配置或使用特定于环境的凭据。

¥When configuring your provider you might want to change the configuration based on the NODE_ENV environment variable or use environment specific credentials.

你可以在 ./config/env/{env}/plugins.js 配置文件中设置特定配置，它将用于覆盖默认配置。

¥You can set a specific configuration in the ./config/env/{env}/plugins.js configuration file and it will be used to overwrite the default configuration.

创建提供者

¥Creating providers

要实现你自己的自定义提供程序，你必须创建 Node.js 模块。

¥To implement your own custom provider you must create a Node.js module.

必须导出的接口取决于你为其开发提供程序的插件。以下是上传和电子邮件插件的模板：

¥The interface that must be exported depends on the plugin you are developing the provider for. Below are templates for the Upload and Email plugins:

Upload
Email

JavaScript
TypeScript

module.exports = {
  init(providerOptions) {
    // init your provider if necessary

    return {
      upload(file) {
        // upload the file in the provider
        // file content is accessible by `file.buffer`
      },
      uploadStream(file) {
        // upload the file in the provider
        // file content is accessible by `file.stream`
      },
      delete(file) {
        // delete the file in the provider
      },
      checkFileSize(file, { sizeLimit }) {
        // (optional)
        // implement your own file size limit logic
      },
      getSignedUrl(file) {
        // (optional)
        // Generate a signed URL for the given file.
        // The signed URL allows secure access to the file.
        // Only Content Manager assets will be signed.
        // Returns an object {url: string}.
      },
      isPrivate() {
        // (optional)
        // if it is private, file urls will be signed
        // Returns a boolean
      },
    };
  },
};

export default {
  init(providerOptions) {
    // init your provider if necessary

    return {
      upload(file) {
        // upload the file in the provider
        // file content is accessible by `file.buffer`
      },
      uploadStream(file) {
        // upload the file in the provider
        // file content is accessible by `file.stream`
      },
      delete(file) {
        // delete the file in the provider
      },
      checkFileSize(file, { sizeLimit }) {
        // (optional)
        // implement your own file size limit logic
      },
      getSignedUrl(file) {
        // (optional)
        // Generate a signed URL for the given file.
        // The signed URL allows secure access to the file.
        // Only Content Manager assets will be signed.
        // Returns an object {url: string}.
      },
      isPrivate() {
        // (optional)
        // if it is private, file urls will be signed
        // Returns a boolean
      },
    };
  },
};

JavaScript
TypeScript

module.exports = {
  init: (providerOptions = {}, settings = {}) => {
    return {
      send: async options => {},
    };
  },
};

export {
  init: (providerOptions = {}, settings = {}) => {
    return {
      send: async options => {},
    };
  },
};

在发送功能中，你将可以访问：

¥In the send function you will have access to:

providerOptions 包含用 plugins.js 编写的配置

¥providerOptions that contains configurations written in plugins.js
settings 包含用 plugins.js 编写的配置

¥settings that contains configurations written in plugins.js
options 包含你从电子邮件插件服务调用发送函数时发送的选项

¥options that contains options you send when you call the send function from the email plugin service

你可以查看 Strapi 维护的提供者以获取示例实现。

¥You can review the Strapi maintained providers for example implementations.

创建新提供者后，你可以发布到 npm 与社区共享，或在本地使用它仅用于你的项目。

¥After creating your new provider you can publish it to npm to share with the community or use it locally for your project only.

本地提供者

¥Local providers

如果你想创建自己的提供程序而不将其发布到 npm 上，你可以按照以下步骤操作：

¥If you want to create your own provider without publishing it on npm you can follow these steps:

在你的应用中创建一个 providers 文件夹。

¥Create a providers folder in your application.
创建你的提供者（例如 ./providers/strapi-provider-<plugin>-<provider>）

¥Create your provider (e.g. ./providers/strapi-provider-<plugin>-<provider>)
然后更新你的 package.json，将你的 strapi-provider-<plugin>-<provider> 依赖链接到新提供者的本地路径。

¥Then update your package.json to link your strapi-provider-<plugin>-<provider> dependency to the local path of your new provider.

{
  ...
  "dependencies": {
    ...
    "strapi-provider-<plugin>-<provider>": "file:providers/strapi-provider-<plugin>-<provider>",
    ...
  }
}

将 ./config/plugins.js 文件更新为配置提供者。

¥Update your ./config/plugins.js file to configure the provider.
最后，运行 yarn install 或 npm install 以安装新的自定义提供程序。

¥Finally, run yarn install or npm install to install your new custom provider.

创建私有提供者

¥Creating private providers

你可以设置私有提供者，这意味着内容管理器中显示的每个资源 URL 都将经过签名以进行安全访问。

¥You can set up a private provider, meaning that every asset URL displayed in the Content Manager will be signed for secure access.

要启用私有提供程序，你必须实现 isPrivate() 方法并返回 true。

¥To enable private providers, you must implement the isPrivate() method and return true.

在后端，Strapi 使用提供程序中实现的 getSignedUrl(file) 方法为每个资源生成签名 URL。签名的 URL 包含一个加密的签名，允许用户访问资源（但通常仅限于有限的时间和特定的限制，具体取决于提供者）。

¥In the backend, Strapi generates a signed URL for each asset using the getSignedUrl(file) method implemented in the provider. The signed URL includes an encrypted signature that allows the user to access the asset (but normally only for a limited time and with specific restrictions, depending on the provider).

请注意，出于安全原因，内容 API 将不会提供任何签名 URL。相反，使用 API 的开发者应该自己对 URL 进行签名。

¥Note that for security reasons, the content API will not provide any signed URLs. Instead, developers using the API should sign the urls themselves.

示例

¥Example

要创建私有 aws-s3 提供者：

¥To create a private aws-s3 provider:

在你的应用中创建一个 ./providers/aws-s3 文件夹。请参阅本地提供者了解更多信息。

¥Create a ./providers/aws-s3 folder in your application. See Local Providers for more information.
在 aws-s3 提供程序中实现 isPrivate() 方法以返回 true。

¥Implement the isPrivate() method in the aws-s3 provider to return true.
在 aws-s3 提供程序中实现 getSignedUrl(file) 方法，为给定文件生成签名 URL。

¥Implement the getSignedUrl(file) method in the aws-s3 provider to generate a signed URL for the given file.

JavaScript
TypeScript

./providers/aws-s3/index.js
// aws-s3 provider

module.exports = {
  init: (config) => {
    const s3 = new AWS.S3(config);

    return {
      async upload(file) {
        // code to upload file to S3
      },

      async delete(file) {
        // code to delete file from S3
      },

      async isPrivate() {
        return true;
      },

      async getSignedUrl(file) {
        const params = {
          Bucket: config.params.Bucket,
          Key: file.path,
          Expires: 60, // URL expiration time in seconds
        };

        const signedUrl = await s3.getSignedUrlPromise("getObject", params);
        return { url: signedUrl };
      },
    };
  },
};

./providers/aws-s3/index.ts
// aws-s3 provider

export = {
  init: (config) => {
    const s3 = new AWS.S3(config);

    return {
      async upload(file) {
        // code to upload file to S3
      },

      async delete(file) {
        // code to delete file from S3
      },

      async isPrivate() {
        return true;
      },

      async getSignedUrl(file) {
        const params = {
          Bucket: config.params.Bucket,
          Key: file.path,
          Expires: 60, // URL expiration time in seconds
        };

        const signedUrl = await s3.getSignedUrlPromise("getObject", params);
        return { url: signedUrl };
      },
    };
  },
};

安装提供程序​

配置提供者​

每个环境的配置​

创建提供者​

本地提供者​

创建私有提供者​