Data Portability API 메서드 호출

Data Portability API는 다음 메서드로 구성됩니다.

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive
  • archiveJobs.cancelPortabilityArchive
  • accessType.check

portabilityArchive.initiate

portabilityArchive.initiate 메서드를 호출하여 새 데이터 내보내기 작업을 시작합니다.

데이터 보관처리를 만들기 위한 내보내기 작업을 시작할 때는 적절한 리소스 그룹을 요청하고 해당 리소스 그룹에 필요한 범위가 포함된 OAuth 토큰을 제공해야 합니다. OAuth 토큰은 요청을 승인하고 내보내는 사용자 데이터를 결정하는 데 사용됩니다.

특정 서비스에서 지원하는 모든 리소스 그룹의 목록은 해당 서비스의 스키마 참조 페이지를 참고하세요.

예를 들어 검색 활동 데이터를 내보내는 경우 InitiatePortabilityArchive(resources = ["myactivity.search"])를 호출합니다. 요청에는 검색 OAuth 범위(https://www.googleapis.com/auth/dataportability.myactivity.search)가 연결된 OAuth 토큰이 있어야 합니다.

단일 InitiatePortabilityArchive 호출에 여러 리소스 그룹을 포함할 수 있지만 권장하지 않습니다. 각 리소스 그룹에 대해 별도의 InitiatePortabilityArchive 요청을 실행하면 처리 속도를 높일 수 있습니다. 여러 리소스 그룹을 요청하는 경우 연결된 OAuth 토큰에 적절한 범위가 모두 연결되어 있어야 합니다.

예를 들어 InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"])를 호출하여 검색 및 YouTube 활동의 데이터 보관 파일을 모두 만드는 대신 InitiatePortabilityArchive(resources = ["myactivity.search"]) 및 InitiatePortabilityArchive(resources = ["myactivity.youtube"])를 별도로 호출합니다.

InitiatePortabilityArchive 요청은 job_id를 반환합니다. 이 작업 ID는 데이터 보관 파일의 상태를 검색하는 데 사용됩니다.

archiveJobs.getPortabilityArchiveState

archiveJobs.getPortabilityArchiveState 메서드는 데이터 보관 파일 내보내기 작업의 현재 상태를 검색하기 위해 호출됩니다. getPortabilityArchiveState를 호출할 때 job_id:GetPortabilityArchiveState(job_id)를 제공합니다. 또한 initiate 요청에 사용된 리소스 그룹과 일치하는 범위가 있는 OAuth 토큰을 제공해야 합니다.

상태가 COMPLETE인 경우 데이터를 다운로드하는 데 사용할 수 있는 서명된 Cloud Storage URL이 반환됩니다. 서명된 URL은 6시간 후에 만료되며 데이터는 14일 동안 사용할 수 있습니다.

보관 파일 요청은 데이터 양에 따라 완료하는 데 몇 분, 몇 시간 또는 며칠이 걸릴 수 있습니다. 5분에서 60분마다 보관처리 상태를 확인할 수 있습니다.

resetAuthorization

resetAuthorization 메서드는 다음을 실행합니다.

  • 사용자가 부여한 모든 OAuth 범위를 취소합니다.
  • 애플리케이션이 이전에 사용한 리소스 그룹에 대해 InitiatePortabilityArchive를 호출할 수 있습니다.
  • 이전 데이터 보관 파일에 대한 액세스 권한을 삭제합니다.

resetAuthorization를 호출할 때는 승인을 재설정할 사용자의 연결된 OAuth 토큰을 제공해야 합니다.

archiveJobs.retryPortabilityArchive

archiveJobs.retryPortabilityArchive 메서드는 archiveJobs.getPortabilityArchiveState 메서드가 이미 FAILED의 상태를 반환한 실패한 작업을 다시 시도하기 위해 호출됩니다. 이는 백엔드의 일시적인 오류로 인해 발생할 수 있습니다. 이 경우 사용자로부터 새 OAuth 토큰을 가져오지 않고 내보내기를 다시 시도할 수 있습니다. retryPortabilityArchive를 호출할 때 유효한 OAuth 토큰과 함께 job_id를 제공합니다. 그러면 엔드포인트는 초기 initiatePortabilityArchive 요청에서 요청한 동일한 리소스 그룹의 내보내기를 만들려고 시도합니다. 성공하면 이 엔드포인트는 getPortabilityArchiveState 호출에 사용할 수 있는 새 job_id를 반환합니다. 실패한 작업은 최대 3회까지 다시 시도할 수 있습니다.

예를 들면 다음과 같습니다.

  1. InitiatePortabilityArchive(resources = ["myactivity.search"])를 호출하면 job_id: 0이 수신됩니다.

  2. GetPortabilityArchiveState(0)를 호출하면 JobSate: FAILED이 수신됩니다.

  3. 그런 다음 RetryPortabilityArchive(0)를 호출하여 resources = ["myactivity.search"]의 job_id: 1를 수신할 수 있습니다.

  4. 그런 다음 GetPortabilityArchiveState(1)를 계속 호출할 수 있습니다.

archiveJobs.cancelPortabilityArchive

archiveJobs.cancelPortabilityArchive 메서드는 사용자 데이터에 대한 액세스가 계속되는 동안 기존 토큰을 취소하지 않고 개별 작업을 취소하기 위해 호출됩니다. 이는 작업 또는 리소스가 더 이상 필요하지 않고 작업 할당량을 재설정하려는 경우에 유용합니다. 작업이 IN_PROGRESS이고 시간 기반 액세스로 생성된 경우에만 취소할 수 있습니다.

예를 들어 myactivity.youtube 및 youtube.public_videos의 진행 중인 시간 기반 작업을 취소한 후 myactivity.youtube에 대해서만 새 작업을 시작할 수 있습니다.

accessType.check

accessType.check 메서드를 사용하면 작업을 시작하기 전에 OAuth 토큰이 시간 기반 액세스 또는 일회성 액세스를 승인하는지 확인할 수 있습니다. 예를 들어 사용자가 일회성 액세스 권한을 부여하는 경우 사용자의 전체 기록을 내보내고, 시간 기반 액세스 권한을 부여하는 경우에는 마지막 날짜만 내보낼 수 있습니다.

응답에는 두 필드가 포함됩니다. 요청에 사용된 OAuth 토큰으로 승인된 일회성 및 시간 기반 데이터 이동성 리소스 그룹 ID 목록입니다. 사용자는 토큰 부여에서 액세스 유형을 혼합할 수 없지만 향후 이러한 동작을 반드시 가정해서는 안 됩니다.