S3 어댑터 연결하기
S3 어댑터는 AWS S3 또는 S3 호환 스토리지의 버킷을 Office 문서 저장소로 연결합니다. 전체 버킷을 사용하거나 프리픽스를 지정해 특정 경로 아래의 문서만 사용할 수 있습니다.
연결 정보 준비하기
사용할 버킷, 리전과 액세스 키를 준비합니다. S3 호환 스토리지는 서비스의 엔드포인트와 SSL·경로 스타일 요구 사항도 확인합니다.
S3 어댑터 추가하기
아래 캡처는 관리자 화면의 AWS S3 추가 양식입니다. 실제 연결에는 사용하는 스토리지의 값을 입력합니다.
- Office 관리자 페이지의 외부연동에서 어댑터 추가를 누릅니다.
- 어댑터 유형에서 AWS S3 또는 S3 호환을 선택합니다.
- 다음 연결 정보를 입력합니다.
| 항목 | 입력할 값 |
|---|---|
| 이름 | 문서 URL에 사용할 고유한 어댑터 이름. 예: company-s3 |
| 설명 | 어댑터의 용도 |
| 액세스 키 | 버킷에 접근할 액세스 키 |
| 보안 액세스 키 | 액세스 키에 대응하는 비밀 키 |
| 리전 | 버킷의 리전. 목록에 없으면 직접 입력 선택 |
| 버킷 | 버킷 이름만 입력. s3://나 경로는 포함하지 않음 |
| 프리픽스 | 사용할 경로. 예: office-documents. 비워 두면 버킷 루트 사용 |
| 세션 토큰 | 임시 자격 증명을 사용할 때 함께 받은 세션 토큰 |
S3 호환 스토리지의 추가 항목
| 항목 | 입력할 값 |
|---|---|
| 엔드포인트 | 스토리지의 도메인 또는 IP와 포트. 예: storage.example.com:9000 |
| 경로 스타일 강제 사용 | 스토리지가 요구하는 경우 사용 선택 |
| SSL 사용 | HTTPS 연결이면 사용, HTTP 연결이면 사용 안 함 선택 |
엔드포인트에 경로·쿼리 문자열을 넣지 않습니다. 주소에 http:// 또는 https://를 함께 입력했다면
SSL 사용 선택도 같은 방식으로 맞춥니다.
문서 암호화
문서 저장 시 암호화를 선택하고 문서 암호화 키를 입력하면 문서를 저장할 때 암호화합니다. 기존 문서도 열어 저장하면 암호화되며, 암호화 사용 여부와 키는 어댑터 등록 후 변경할 수 없습니다.
암호화 키를 잃어버리거나 암호화를 설정한 S3 어댑터 정보를 삭제해도, S3에 저장된 문서는 암호화된 상태로 남습니다. 같은 암호화 키와 연결 설정을 복구하지 못하면 문서를 열 수 없으므로, 키와 어댑터 설정을 별도로 안전하게 보관합니다.
연결 확인 및 등록하기
- 연결 테스트를 누릅니다.
- 연결과 파일 목록 조회에 성공하면 등록을 누릅니다.
- 등록한 어댑터 이름과 프리픽스를 기준으로 한 문서 상대 경로로 문서 URL을 생성합니다.
- 테스트용 문서를 열어 편집하고 저장한 뒤, 다시 열어 변경 내용이 유지되는지 확인합니다.
목록 조회 성공만으로 문서 저장 권한까지 확인되지는 않습니다. 연결 테스트가 실패하면 키·리전·버킷·엔드포인트와 목록 조회 권한을 확인하고, 문서는 열리지만 저장되지 않는다면 쓰기 권한을 확인합니다.
문서 URL 만들기
위 캡처에 입력한 어댑터 이름 company-s3, 버킷 company-documents, 프리픽스 office-documents를 기준으로 문서를 엽니다. 다음 예제는 프리픽스 아래에 reports/Quarterly Report.docx가 있는 경우입니다.
| 항목 | 값 |
|---|---|
| Office 주소 | http://localhost:8080 |
| 이름 | company-s3 |
| 버킷 | company-documents |
| 프리픽스 | office-documents |
| 버킷 안의 객체 키 | office-documents/reports/Quarterly Report.docx |
| URL에 넣을 문서 경로 | reports/Quarterly Report.docx |
Office 주소 뒤에 /cloud-office/api/, 어댑터 이름, 프리픽스 아래의 상대 경로와 /open을 붙입니다.
http://localhost:8080/cloud-office/api/company-s3/reports/Quarterly%20Report.docx/open?app=WORD_EDITOR&user_id=local-user&docId=s3report001
버킷 이름, 리전과 프리픽스는 어댑터 설정으로 결정되므로 Office URL에 다시 넣지 않습니다. 프리픽스를 비워 두었다면 버킷 안의 객체 키 전체가 문서 상대 경로가 됩니다. S3 호환 스토리지도 같은 방식으로 조합합니다.
Office 주소·포트, 어댑터 이름과 문서 경로를 실제 설정에 맞게 바꿉니다. 폴더 구분자 /는 유지하고 공백은 %20처럼 경로 세그먼트별로 URL 인코딩합니다. 사용자 식별자와 고유한 문서 식별자, 파일 종류별 app 값과 전체 옵션은 문서 URL 생성에서 확인합니다.