임베디드 콘텐츠¶

리치 텍스트¶

Wagtail의 기본 리치 텍스트 편집기에는 리치 텍스트에 임베드를 배치할 수 있는 “미디어” 아이콘이 있습니다. 이를 활성화하기 위해 특별히 할 일은 없습니다. 단지 리치 텍스트 필드의 내용이 템플릿에서 |richtext 필터를 통과하도록 해야 합니다. 이것이 임베드 모듈을 호출하여 임베드 코드를 가져오고 중첩하는 역할을 합니다.

EmbedBlock StreamField 블록 타입¶

EmbedBlock 블록 타입을 사용하면 임베드를 StreamField 에 배치할 수 있습니다.

max_width 와 max_height 인수는 임베드 코드를 가져올 때 제공자에게 전송됩니다.

예를 들면:

from wagtail.embeds.blocks import EmbedBlock

class MyStreamField(blocks.StreamBlock):
    ...

    embed = EmbedBlock(max_width=800, max_height=400)

{% embed %} 태그¶

구문: {% embed <url> [max_width=<max width>] %}

URL과 선택적 max_width 인수를 {% embed %} 태그에 전달하여 임베드를 템플릿에 중첩할 수 있습니다.

max_width 인수는 임베드 코드를 가져올 때 제공자에게 전송됩니다.

{% load wagtailembeds_tags %}

{# YouTube 동영상 임베드 #}
{% embed 'https://www.youtube.com/watch?v=Ffu-2jEdLPw' %}

{# 이 태그는 변수에서 URL을 가져올 수도 있습니다 #}
{% embed page.video_url %}

Python에서 사용하기¶

URL 문자열을 받아 Embed 객체를 반환하는 내부 get_embed 함수를 호출할 수도 있습니다(아래 모델 문서 참조). 이 함수는 임베드 코드를 가져올 때 제공자에게 전송되는 max_width 키워드 인수도 받습니다.

from wagtail.embeds.embeds import get_embed
from wagtail.embeds.exceptions import EmbedException

try:
    embed = get_embed('https://www.youtube.com/watch?v=Ffu-2jEdLPw')

    print(embed.html)
except EmbedException:
    # 임베드를 찾을 수 없음
    pass

oEmbed (기본값)¶

기본 임베드 파인더는 oEmbed 프로토콜을 사용하여 콘텐츠 제공자로부터 직접 임베드 코드를 가져옵니다. Wagtail에는 기본적으로 모두 활성화된 내장 제공자 목록이 있습니다. 다음 링크에서 해당 제공자 목록을 찾을 수 있습니다:

https://github.com/wagtail/wagtail/blob/main/wagtail/embeds/oembed_providers.py

from wagtail.embeds.oembed_providers import youtube, vimeo

# 사용자 정의 제공자 추가
# 이 작업을 위해서는 사용자 정의 제공자가 oEmbed를 지원해야 합니다.
# 제공자의 문서에서 이러한 세부 정보를 찾을 수 있어야 합니다.
# - 'endpoint'는 Wagtail이 호출할 oEmbed 엔드포인트의 URL입니다
# - 'urls'는 어떤 패턴을 지정합니다
my_custom_provider = {
    'endpoint': 'https://customvideosite.com/oembed',
    'urls': [
        '^http(?:s)?://(?:www\\.)?customvideosite\\.com/[^#?/]+/videos/.+$',
    ]
}

WAGTAILEMBEDS_FINDERS = [
    {
        'class': 'wagtail.embeds.finders.oembed',
        'providers': [youtube, vimeo, my_custom_provider],
    }
]

from wagtail.embeds.oembed_providers import youtube


WAGTAILEMBEDS_FINDERS = [
    # YouTube 동영상을 가져오지만 YouTube의 oEmbed 엔드포인트를 호출할 때
    # GET 매개변수에 ``?scheme=https`` 를 넣습니다
    {
        'class': 'wagtail.embeds.finders.oembed',
        'providers': [youtube],
        'options': {'scheme': 'https'}
    },

    # 다른 모든 oEmbed 제공자를 기본 방식으로 처리합니다
    {
        'class': 'wagtail.embeds.finders.oembed',
    }
]

Facebook 및 Instagram¶

2020년 10월부터 Meta는 공개 oEmbed API를 더 이상 사용하지 않습니다. 사이트에 Facebook 또는 Instagram 게시물을 임베드하려면 새로운 인증된 API를 사용해야 합니다. 이를 위해서는 Meta 개발자 계정을 설정하고 _oEmbed Product_를 포함하는 Facebook 앱을 만들어야 합니다. 필요한 앱을 만드는 지침은 Facebook과 Instagram 문서의 요구 사항 섹션에 있습니다.

2021년 6월부터 _oEmbed Product_는 oEmbed Read 기능으로 대체되었습니다. Facebook 및 Instagram 게시물을 임베드하려면 앱이 oEmbed Read 기능을 활성화해야 합니다. 또한 앱은 Meta에 의해 검토되고 승인되어야 합니다. API 변경 로그에서 발표를 확인할 수 있습니다.

2021년 6월 8일 이전에 oEmbed Product를 활성화한 앱은 2021년 9월 7일 이전에 oEmbed Read 기능을 활성화하고 앱을 검토해야 합니다.

앱 액세스 토큰(App ID 및 App Secret)이 있으면 WAGTAILEMBEDS_FINDERS 설정에 Facebook 및/또는 Instagram 파인더를 추가하고 앱에서 App ID와 App Secret로 구성하세요:

WAGTAILEMBEDS_FINDERS = [
    {
        'class': 'wagtail.embeds.finders.facebook',
        'app_id': '여기에 FACEBOOK APP_ID 입력',
        'app_secret': '여기에 FACEBOOK APP_SECRET 입력',
    },
    {
        'class': 'wagtail.embeds.finders.instagram',
        'app_id': '여기에 INSTAGRAM APP_ID 입력',
        'app_secret': '여기에 INSTAGRAM APP_SECRET 입력',
    },

    # 다른 모든 oEmbed 제공자를 기본 방식으로 처리
    {
        'class': 'wagtail.embeds.finders.oembed',
    }
]

기본적으로 Facebook 및 Instagram 임베드에는 임베드를 완전히 렌더링하는 데 필요한 JavaScript가 포함됩니다. 특정 경우에는 이것이 원하는 것이 아닐 수 있습니다 - 예를 들어, 여러 Facebook 임베드가 있는 경우 여러 스크립트 태그가 생성됩니다. 구성에서 'omitscript': True 를 전달하여 이러한 스크립트 태그가 임베드 HTML에서 생략되어야 함을 나타낼 수 있습니다. 이 경우 이 스크립트를 직접 로드해야 합니다.

Embed.ly¶

Embed.ly는 oEmbed 프로토콜을 구현하지 않는 사이트에 대한 임베드를 제공할 수 있는 유료 서비스입니다.

또한 임베드에 일관된 모양을 제공하고 공통 비디오 재생 API를 제공하는 등의 유용한 기능을 제공합니다. 이는 사이트에서 비디오가 다른 제공자에 호스팅되도록 허용하고 사용자 정의 컨트롤을 구현해야 하는 경우 유용합니다.

Wagtail에는 Embed.ly에서 임베드를 가져오는 내장 지원이 있습니다. 이를 사용하려면 먼저 pip을 통해 Embedly 파이썬 패키지를 설치하세요.

이제 wagtail.embeds.finders.oembed 클래스를 사용하는 임베드 파인더를 WAGTAILEMBEDS_FINDERS 설정에 추가하고 API 키를 전달하세요:

WAGTAILEMBEDS_FINDERS = [
    {
        'class': 'wagtail.embeds.finders.embedly',
        'key': '여기에 EMBED.LY 키 입력'
    }
]

사용자 정의 임베드 파인더 클래스¶

완전한 제어를 위해 사용자 정의 파인더 클래스를 만들 수 있습니다.

다음은 뼈대로 사용할 수 있는 기본 파인더 클래스입니다. 각 메서드가 수행하는 작업에 대한 자세한 내용은 독스트링을 읽어보세요:

from wagtail.embeds.finders.base import EmbedFinder


class ExampleFinder(EmbedFinder):
    def __init__(self, **options):
        pass

    def accept(self, url):
        """
        이 파인더가 URL에 대한 임베드를 가져오는 방법을 알고 있으면 True를 반환합니다.

        이것은 부작용이 없어야 합니다(외부 서버에 요청 없음)
        """
        pass

    def find_embed(self, url, max_width=None):
        """
        URL과 최대 너비를 가져와 사이트에 임베딩하는 데 사용할 콘텐츠에 대한
        정보 사전을 반환합니다.

        이 부분은 외부 API에 요청을 할 수 있습니다.
        """
        # TODO: 요청 수행

        return {
            'title': "콘텐츠 제목",
            'author_name': "작성자 이름",
            'provider_name': "제공자 이름(예: YouTube, Vimeo 등)",
            'type': "'photo', 'video', 'link' 또는 'rich' 중 하나",
            'thumbnail_url': "썸네일 이미지 URL",
            'width': 픽셀_단위_너비,
            'height': 픽셀_단위_높이,
            'html': "<h2>임베드 HTML</h2>",
        }

이러한 모든 메서드를 구현한 후에는 WAGTAILEMBEDS_FINDERS 설정에 추가하기만 하면 됩니다:

WAGTAILEMBEDS_FINDERS = [
    {
        'class': '여기에.파인더.클래스.경로',
        # 다른 옵션은 __init__ 메서드에 kwargs로 전달됩니다
    }
]

임베드 삭제하기¶

임베드 구성이 손상되지 않는 한, Embed 모델의 항목을 삭제하는 것은 완전히 안전해야 합니다. Wagtail은 사이트에서 사용 중인 레코드를 자동으로 다시 채웁니다.

oEmbed에서 Embedly로 또는 그 반대로 변경한 경우 이 작업을 수행할 수 있습니다. 생성하는 임베드 코드가 약간 다를 수 있으며 사이트에 일관성이 없을 수 있기 때문입니다.

일반적으로 임베드 설정을 변경할 때마다 purge_embeds 명령을 사용하여 Embed 객체를 지우는 것이 좋습니다.