Active Storage

Active Storage упрощает загрузку и ссылку на файлы в облачных сервисах, таких как Amazon S3, Google Cloud Storage или Microsoft Azure Storage, и прикрепление этих файлов к записям Active Record. Поддерживает один основной сервис и зеркала в других сервисах для повышения отказоустойчивости. Также предоставляет дисковый сервис для тестирования или локальных развертываний, но основное внимание уделяется облачному хранилищу.

Файлы могут загружаться с сервера в облако или напрямую с клиента в облако.

Изображения могут быть дополнительно преобразованы с помощью вариативных вариантов по требованию для качества, соотношения сторон, размера или любых других поддерживаемых преобразований MiniMagick или Vips.

Дополнительную информацию об Active Storage вы можете найти в руководстве Обзор Active Storage.

Сравнение с другими решениями хранилища

Ключевое отличие работы Active Storage от других решений для прикрепления файлов в Rails заключается в использовании встроенных моделей Blob и Attachment (поддерживаемых Active Record). Это означает, что существующие модели приложения не требуют модификаций с добавлением дополнительных столбцов для связывания с файлами. Active Storage использует полиморфные ассоциации через модель объединения Attachment, которая затем подключается к фактической Blob.

Модели Blob хранят метаданные прикрепления (имя файла, тип содержимого и т. д.) и ключ идентификатора в службе хранения. Модели Blob не хранят фактические двоичные данные. Они предназначены для неизменяемости. Один файл, один blob. Вы можете связать один и тот же blob с несколькими моделями приложения. И если вам нужно выполнить преобразование заданного Blob, идея заключается в создании нового, а не попытке изменить существующий (хотя, конечно, вы можете удалить предыдущую версию позже, если она вам больше не нужна).

Установка

Запустите bin/rails active_storage:install для копирования миграций active_storage.

ПРИМЕЧАНИЕ: Если задача не найдена, проверьте, что require "active_storage/engine" присутствует в config/application.rb.

Примеры

Одно прикрепление:

class User < ApplicationRecord
  # Associates an attachment and a blob. When the user is destroyed they are
  # purged by default (models destroyed, and resource files deleted).
  has_one_attached :avatar
end

# Attach an avatar to the user.
user.avatar.attach(io: File.open("/path/to/face.jpg"), filename: "face.jpg", content_type: "image/jpeg")

# Does the user have an avatar?
user.avatar.attached? # => true

# Synchronously destroy the avatar and actual resource files.
user.avatar.purge

# Destroy the associated models and actual resource files async, via Active Job.
user.avatar.purge_later

# Does the user have an avatar?
user.avatar.attached? # => false

# Generate a permanent URL for the blob that points to the application.
# Upon access, a redirect to the actual service endpoint is returned.
# This indirection decouples the public URL from the actual one, and
# allows for example mirroring attachments in different services for
# high-availability. The redirection has an HTTP expiration of 5 min.
url_for(user.avatar)

class AvatarsController < ApplicationController
  def update
    # params[:avatar] contains an ActionDispatch::Http::UploadedFile object
    Current.user.avatar.attach(params.require(:avatar))
    redirect_to Current.user
  end
end

Несколько прикреплений:

class Message < ApplicationRecord
  has_many_attached :images
end

<%= form_with model: @message, local: true do |form| %>
  <%= form.text_field :title, placeholder: "Title" %><br>
  <%= form.text_area :content %><br><br>

  <%= form.file_field :images, multiple: true %><br>
  <%= form.submit %>
<% end %>

class MessagesController < ApplicationController
  def index
    # Use the built-in with_attached_images scope to avoid N+1
    @messages = Message.all.with_attached_images
  end

  def create
    message = Message.create! params.require(:message).permit(:title, :content, images: [])
    redirect_to message
  end

  def show
    @message = Message.find(params[:id])
  end
end

Variation варианта изображения прикрепления:

<%# Hitting the variant URL will lazy transform the original blob and then redirect to its new service location %>
<%= image_tag user.avatar.variant(resize_to_limit: [100, 100]) %>

File стратегии предоставления файлов

Active Storage поддерживает два способа предоставления файлов: перенаправление и проксирование.

Перенаправление

Active Storage генерирует стабильные URL-адреса приложения для файлов, которые при доступе перенаправляются на подписанные, кратковременные URL-адреса сервиса. Это снимает с серверов приложения нагрузку по предоставлению данных файла. Это — стратегия предоставления файлов по умолчанию.

Если приложение настроено по умолчанию на проксирование файлов, используйте помощники маршрутов rails_storage_redirect_path и _url для перенаправления вместо этого:

<%= image_tag rails_storage_redirect_path(@user.avatar) %>

Проксирование

В качестве альтернативы файлы можно проксировать. Это означает, что серверы приложения будут загружать данные файла из службы хранения в ответ на запросы. Это может быть полезно для предоставления файлов с CDN.

Вы можете настроить Active Storage на использование проксирования по умолчанию:

# config/initializers/active_storage.rb
Rails.application.config.active_storage.resolve_model_to_route = :rails_storage_proxy

Или, если вы хотите явно проксировать определенные прикрепления, вы можете использовать помощники URL-адресов в форме rails_storage_proxy_path и rails_storage_proxy_url.

<%= image_tag rails_storage_proxy_path(@user.avatar) %>

Прямые загрузки

Active Storage с его включённой JavaScript-библиотекой поддерживает прямую загрузку с клиента в облако.

Установка прямой загрузки

1. Включите Active Storage JavaScript в пакет JavaScript вашего приложения или обратитесь к нему напрямую.

   Требование напрямую без сборки через asset pipeline в HTML-приложения с автозапуском:

   <%= javascript_include_tag "activestorage" %>

   Требование через importmap-rails без сборки через asset pipeline в HTML-приложении без автозапуска как ESM:

   # config/importmap.rb
   pin "@rails/activestorage", to: "activestorage.esm.js"
   

   <script type="module-shim">
     import * as ActiveStorage from "@rails/activestorage"
     ActiveStorage.start()
   </script>

   Использование asset pipeline:

   //= require activestorage

   Использование пакета npm:

   import * as ActiveStorage from "@rails/activestorage"
   ActiveStorage.start()

2. Разместите поля ввода файлов с URL-адресом прямой загрузки.

   <%= form.file_field :attachments, multiple: true, direct_upload: true %>

3. Всё готово! Загрузки начинаются при отправке формы.

События JavaScript для прямой загрузки

Лицензия

Active Storage распространяется по лицензии MIT.

Поддержка

Документация API находится по адресу:

• api.rubyonrails.org

Сообщения об ошибках для проекта Ruby on Rails можно отправлять здесь:

• github.com/rails/rails/issues

Запросы на новые функции следует обсудить на почтовом списке rails-core по этому адресу:

• discuss.rubyonrails.org/c/rubyonrails-core