홈페이지에 콘텐츠 연동하기

외부 공개한 컬렉션의 콘텐츠는 주소로 불러올 수 있습니다. 홈페이지를 만드는 담당자가 이 주소로 공지사항이나 자주 묻는 질문을 가져오면, 화면에서 콘텐츠를 고칠 때마다 홈페이지 내용도 함께 갱신됩니다. 이 글은 연동에 필요한 정보를 찾고 전달하는 방법을 안내합니다.

시작하기 전에#

• 컬렉션의 외부 공개가 활성화되어 있어야 합니다. 비공개 컬렉션은 연동 주소로 조회되지 않습니다. 설정은 콘텐츠 컬렉션 만들기를 참고합니다.
• 공개 상태인 콘텐츠만 제공됩니다. 임시 저장 콘텐츠와 예약 시각이 지나지 않은 콘텐츠는 제외됩니다.
• 공개 키로 요청하려면 요청의 Origin 또는 Referer 헤더가 사이트에 등록된 도메인과 같아야 합니다. 브라우저는 이 헤더를 자동으로 보냅니다. 도메인은 사이트 설정에서 확인합니다.
• 홈페이지 코드는 개발자가 작성합니다. 개발자에게 이 글의 주소와 인증 방법을 전달합니다.

순서#

1. 사이트 > 사이트 관리 > 콘텐츠 > 외부 연동을 선택합니다. 컬렉션 목록 오른쪽 위 외부 연동 버튼으로도 열 수 있습니다.
2. 공개한 콘텐츠 영역에서 컬렉션별 가져올 주소를 확인합니다. 주소 복사를 선택하면 복사됩니다. 안내 문구대로 이 주소를 홈페이지 제작 담당자에게 전달합니다.
3. 개발자에게 필요한 정보는 개발자용 상세를 펼쳐 확인합니다. 인증, 엔드포인트, 요청 예시가 있습니다.
4. 인증에 사용하는 사이트 키는 사이트 > 설정 > 사이트 설정의 사이트 키 영역에서 복사합니다. 연동에는 공개 키를 사용합니다.
5. 요청 예시를 복사해 홈페이지 코드에서 사용합니다.

외부 연동 화면. 개발자용 상세에 인증 방법, 엔드포인트, 요청 예시가 표시됩니다.

주소와 인증#

{컬렉션}에는 컬렉션의 영문 이름(예: notice)을 입력합니다. 서버나 터미널에서 공개 키로 시험할 때는 -H "Origin: https://등록한도메인"을 함께 보냅니다. 서버에서만 호출한다면 비공개 키로도 조회할 수 있습니다. {id}에는 목록 응답에 있는 콘텐츠의 ulid를 입력합니다. 외부 연동 화면의 주소는 화면에 표시된 도메인을 그대로 사용합니다.

요청 예시#

curl -H "Authorization: Bearer <공개 키>" \
"https://did.kr/api/v1/cms/{컬렉션}/entries"

응답에 담기는 정보#

• 목록 응답: collection(영문 이름, 이름, 유형), entries(콘텐츠 배열), meta(page, per_page, total, last_page)
• 콘텐츠 한 건: ulid, title, is_pinned, published_at, fields(필드의 영문 이름별 값)
• 쪽수는 page, 한 번에 가져올 개수는 per_page로 정합니다. per_page는 1에서 100까지이며 기본값은 20입니다.
• 상단 고정한 콘텐츠가 맨 앞에 오고, 나머지는 컬렉션의 기본 정렬을 따릅니다.
• 단일형 컬렉션의 값은 응답 entries의 첫 번째 항목에 있습니다.

이후에는#

• 공개 상태의 콘텐츠를 등록하거나 수정하면 연동 주소의 응답이 1분 안에 갱신됩니다. 응답은 1분간 캐시됩니다.
• 컬렉션의 외부 공개를 해제하면 해당 주소는 「컬렉션을 찾을 수 없습니다.」(404)로 응답합니다.
• 필드를 삭제하면 해당 필드는 응답에서 빠집니다.

안 될 때#

관련 글#

• 콘텐츠 컬렉션 만들기
• 콘텐츠 등록하고 수정하기
• 외부 랜딩페이지에서 API로 리드 접수하기