인증 및 설정
Dropbox 통합은 Scoped Access 접근 방식을 사용하는 OAuth 2.0 인증을 사용합니다. 조직은 Dropbox App Console에서 Dropbox App을 생성하고 적절한 권한을 구성해야 합니다. 이 통합은 개인 Dropbox 계정과 Dropbox Business 팀 계정을 모두 지원합니다. 적절한 인증을 통해 에이전트는 사용자의 Dropbox 또는 공유 팀 폴더의 파일에 접근할 수 있습니다.필요한 권한 및 범위
- files.content.write: 파일 콘텐츠를 업로드하고 수정합니다.
- files.content.read: 파일 콘텐츠를 다운로드하고 읽습니다.
- files.metadata.write: 폴더를 생성하고, 파일을 이동, 이름 변경 및 삭제합니다.
- files.metadata.read: 파일 및 폴더 메타데이터를 봅니다.
- sharing.write: 공유 링크를 생성하고 수정합니다.
- sharing.read: 기존 공유 설정을 봅니다.
- team_data.member: 팀 폴더 콘텐츠에 접근합니다(Dropbox Business).
사용 가능한 작업
모든 필요한 권한이 구성되면 툴킷은 다음 작업을 활성화합니다.파일 작업
- 파일 업로드: 자동 버전 관리와 함께 에이전트 워크스페이스에서 Dropbox로 파일을 업로드합니다.
- 파일 다운로드: 부분 다운로드를 지원하여 로컬 처리를 위해 파일을 검색합니다.
- 파일 이동: 자동 충돌 해결과 함께 폴더 간에 파일을 재배치합니다.
- 파일 복사: 동일하거나 다른 위치에 파일을 복제합니다.
- 파일 삭제: 파일을 제거합니다(삭제된 파일에서 30일간 복구 가능).
- 파일 복원: 삭제된 파일을 복구하거나 이전 버전을 복원합니다.
- 파일 메타데이터 가져오기: 크기, 수정 날짜, 콘텐츠 해시를 포함한 파일 세부 정보를 검색합니다.
- 파일 검색: 파일 이름 및 콘텐츠에서 전체 텍스트 검색(지원되는 경우).
- 섬네일 가져오기: 이미지 및 문서에 대한 미리보기 섬네일을 생성합니다.
폴더 관리
- 폴더 생성: 중첩된 계층 구조로 새 폴더를 생성합니다.
- 폴더 목록: 페이지네이션 지원으로 폴더 내용을 탐색합니다.
- 폴더 이동: 전체 폴더 구조를 재배치합니다.
- 폴더 복사: 모든 내용과 함께 폴더를 복제합니다.
- 폴더 삭제: 폴더와 모든 내용을 제거합니다.
- 폴더 메타데이터 가져오기: 폴더 속성 및 통계를 검색합니다.
공유 작업
- 공유 링크 생성: 공개 또는 비밀번호로 보호되는 공유 링크를 생성합니다.
- 공유 링크 목록: 파일 및 폴더의 모든 활성 공유 링크를 봅니다.
- 공유 링크 취소: 추가 접근을 방지하기 위해 공유 링크를 비활성화합니다.
- 링크 설정 업데이트: 링크 권한 및 만료 날짜를 수정합니다.
- 공유 폴더 생성: 특정 사용자 또는 팀과 폴더를 공유합니다.
- 폴더 멤버 추가: 공유 폴더에서 협업하도록 사용자를 초대합니다.
- 폴더 멤버 제거: 공유 폴더 협업자의 접근을 취소합니다.
- 링크 만료 설정: 자동 링크 만료 날짜를 구성합니다.
- 링크 비밀번호 설정: 비밀번호 인증으로 링크를 보호합니다.
고급 작업
- 파일 리비전 가져오기: 파일에 대한 버전 기록에 접근합니다(30일 또는 더 긴 확장 기록).
- 일괄 작업: 단일 API 호출에서 여러 파일 작업을 수행합니다.
- 업로드 세션: 청크 업로드 세션을 사용하여 대용량 파일(150MB 이상)을 업로드합니다.
- ZIP 다운로드: 압축 아카이브로 여러 파일을 다운로드합니다.
- 사용량 가져오기: 계정 스토리지 사용량 및 사용 가능한 공간을 확인합니다.
- Paper 문서 작업: Dropbox Paper 문서를 생성하고 편집합니다.
Dropbox Business 기능
- 팀 폴더 접근: 팀 폴더에 접근하고 관리합니다.
- 멤버 관리: 팀 멤버와 해당 권한을 나열합니다.
- 관리자 작업: 관리자 작업을 수행합니다(관리자 권한 필요).
구성 옵션
- 기본 폴더: Dropbox에서 기본 업로드 위치를 설정합니다.
- 충돌 해결: 파일 이름 충돌 시 동작 선택(자동 이름 변경, 덮어쓰기, 실패).
- 청크 크기: 대용량 파일의 업로드 청크 크기를 구성합니다(기본값 4MB).
- 링크 권한: 공유 링크의 기본 권한(보기 전용, 편집).
- 자동 삭제: 성공적인 업로드 후 로컬 파일을 자동으로 삭제합니다.
사용 사례
- 파일 스토리지: 에이전트 워크스페이스에서 중요한 문서와 데이터를 클라우드로 백업합니다.
- 백업 자동화: 중요한 파일의 자동 백업을 Dropbox에 예약합니다.
- 파일 공유: 이해관계자 접근을 위한 보고서, 문서 또는 데이터 세트의 공유 링크를 생성합니다.
- 협업 워크플로우: 협업을 위해 공유 팀 폴더에 파일을 업로드합니다.
- 문서 배포: 공유 링크를 통해 여러 수신자에게 생성된 보고서를 배포합니다.
- 데이터 마이그레이션: Dropbox를 중간 매체로 사용하여 스토리지 시스템 간에 파일을 전송합니다.
- 버전 관리: 문서 관리를 위한 Dropbox의 자동 버전 관리를 활용합니다.
- 미디어 라이브러리: 이미지, 비디오 및 미디어 자산을 저장하고 구성합니다.
모범 사례
- 경로 식별자 사용: 안정성을 위해 경로로 파일을 참조합니다(대소문자 구분 안 함).
- 청크 업로드: 150MB 이상의 파일에는 항상 업로드 세션을 사용합니다.
- 일괄 요청: API 호출을 줄이기 위해 여러 작업을 그룹화합니다(일괄당 최대 1,000개 작업).
- 속도 제한 모니터링: Dropbox는 속도 제한을 시행합니다. 재시도 시 지수 백오프를 구현합니다.
- 링크 만료: 민감한 콘텐츠에 대한 공유 링크에 만료 날짜를 설정합니다.
- 폴더 구성: 파일을 체계적으로 정리하기 위해 명확한 폴더 계층 구조를 사용합니다.
- 공간 확인: 실패를 방지하기 위해 대용량 업로드 전에 사용 가능한 스토리지를 확인합니다.
속도 제한 및 할당량
Dropbox API는 앱 유형과 계정 등급에 따라 속도 제한을 시행합니다. 표준 제한: 개인 사용자당 초당 40개 요청. 일괄 작업은 단일 요청으로 계산됩니다. HTTP 429 응답을 모니터링하고 지수 백오프로 재시도 로직을 구현합니다(제안: 1초, 2초, 4초, 8초).일반적인 문제 및 해결 방법
- 경로를 찾을 수 없음: 경로 철자와 대소문자를 확인합니다(Dropbox 경로는 대소문자 구분 없지만 대소문자를 보존).
- 공간 부족: 업로드 전에 계정 스토리지를 확인합니다. 필요한 경우 요금제를 업그레이드합니다.
- 속도 제한 초과: 지수 백오프를 구현하고 일괄 작업 사용을 고려합니다.
- 업로드 시간 초과: 네트워크 중단을 처리하기 위해 대용량 파일에는 청크 업로드 세션을 사용합니다.
- 권한 거부: OAuth 범위에 작업에 필요한 권한이 포함되어 있는지 확인합니다.