Data Portability API 사용 시작

이 빠른 시작에서는 계정의 OAuth 토큰을 가져오고 Data Portability API 엔드포인트에 일회성 요청을 전송합니다.

이 빠른 시작에서는 Data Portability API를 사용하여 사용자 데이터에 일회성으로 액세스하는 방법을 설명합니다. 사용자 데이터에 대한 지속적인 액세스 권한은 시간 기반 액세스 사용을 참고하세요. 요청에 시간 필터를 적용하는 방법을 알아보려면 시간 필터 적용을 참고하세요.

학습 내용

이 빠른 시작에서는 다음을 수행하는 방법을 알아봅니다.

유효한 OAuth 토큰을 제공하여 InitiatePortabilityArchive 엔드포인트에 인증된 요청을 보냅니다. 응답에 유효한 job_id가 포함되어야 합니다.
GetPortabilityArchiveState 엔드포인트에 인증된 요청을 보냅니다. 응답에는 유효한 작업 상태가 포함되어야 하며 작업이 완료되면 서명된 URL이 포함되어야 합니다.
(선택사항) 동일한 사용자 인증 정보를 사용하여 유효한 OAuth 토큰이 포함된 인증된 요청을 InitiatePortabilityArchive 엔드포인트에 두 번째로 보냅니다. 이렇게 하면 RESOURCE_EXHAUSTED 오류가 반환되며 ResetAuthorization 엔드포인트의 중요성을 강조하기 위한 것입니다.
ResetAuthorization 엔드포인트에 인증된 요청을 보냅니다. 이 요청은 사용자가 부여한 모든 OAuth 범위를 취소합니다.
(선택사항) 이전에 사용한 것과 동일한 OAuth 토큰을 사용하여 InitiatePortabilityArchive 엔드포인트에 요청을 전송합니다. 승인이 재설정되면 요청이 실패합니다.

기본 요건

이 빠른 시작을 실행하려면 다음을 실행해야 합니다.

거주 중인 지역의 사용자가 Data Portability API를 사용할 수 있는지 확인합니다. 지원되는 국가 및 지역 목록은 '서드 파티와 데이터 사본 공유' 페이지의 일반 질문을 참고하세요.
Data Portability API의 설정 단계를 완료합니다.
단계에 따라 JavaScript 웹 앱에 OAuth를 구성합니다. 프로덕션에서는 일반적으로 웹 서버 애플리케이션의 OAuth 흐름과 같은 다른 흐름을 사용합니다. 편의를 위해 이 빠른 시작에서는 JavaScript 웹 앱 흐름을 사용합니다.
- 승인 사용자 인증 정보를 만들 때 OAuth 2.0 클라이언트 ID와 승인된 리디렉션 URI (예: https://google.com)를 기록해 둡니다. 이 값은 빠른 시작의 뒷부분에서 필요합니다.
- Data Portability API의 범위를 구성할 때 이 빠른 시작에서는 myactivity.search 리소스 그룹(https://www.googleapis.com/auth/dataportability.myactivity.search)을 사용합니다.
- 액세스를 허용할 시간을 선택하면 이 빠른 시작에서는 일회성 액세스를 사용합니다.
OAuth 토큰을 가져옵니다.
조직에서 소유하거나 관리하는 계정에 대한 액세스 권한을 얻습니다. 이 빠른 시작에서는 이 계정의 검색 활동 데이터를 내보냅니다.

OAuth 토큰 가져오기

이 빠른 시작에서는 URL을 사용하여 OAuth 토큰을 가져오기 위한 승인 요청을 보냅니다. 이 프로세스는 JavaScript 웹 앱의 흐름을 사용합니다. 이 흐름은 새로고침 토큰을 반환하지 않습니다.

프로덕션 앱의 경우 일반적으로 OAuth 흐름을 사용하여 필요에 따라 액세스 토큰을 생성하는 데 사용할 수 있는 갱신 토큰을 가져옵니다. 서버 측 웹 앱의 흐름이 그 예입니다.

OAuth 토큰을 가져오는 방법은 다음과 같습니다.

다음과 같은 URL을 작성합니다.
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=token&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value
```
URL에서 다음 사항을 확인합니다.
- client_id는 OAuth 클라이언트 ID입니다.
- redirect_uri는 승인된 리디렉션 URI입니다(예: https://google.com).
이 빠른 시작의 URL에 사용된 범위는 검색 활동 범위입니다. YouTube 활동 범위 또는 두 범위 모두를 사용할 수도 있습니다.

경고: Data Portability API 범위를 다른 유형의 범위와 혼합하거나 한 번에 너무 많은 범위를 사용하거나 이전에 부여된 범위를 포함하면 오류가 발생하므로 주의하세요. 자세한 내용은 범위 제한을 참고하세요.
브라우저의 주소 표시줄에 URL을 붙여넣고 OAuth 흐름의 단계를 따릅니다. 이 흐름을 사용하려면 이 빠른 시작에 사용하는 조직에서 소유하거나 관리하는 계정으로 로그인해야 합니다.

OAuth 범위에 동의하는 계정입니다. 동의 화면은 다음과 같이 표시됩니다 (화면의 텍스트는 이 이미지의 텍스트와 다를 수 있음).
액세스 권한을 부여할 범위와 계정 데이터에 대한 액세스 권한을 공유할 기간 (한 번, 30일 또는 180일)을 선택합니다. 이 빠른 시작에서는 한 번만을 선택합니다.
동의하고 액세스 기간을 선택하면 리디렉션 URI(https://google.com)로 전달됩니다. 주소 표시줄에 생성된 URL에는 OAuth 액세스 토큰이 포함됩니다.

예를 들어 사용자 계정이 dataportability.myactivity.search 범위에 OAuth 액세스 권한을 부여하는 경우 생성된 URL은 다음과 같습니다.
```
https://google.com/#state=developer-specified-value&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
URL에서 your_OAuth_token는 토큰을 나타내는 문자열입니다.

중요: OAuth 액세스 토큰은 1시간 후에 만료됩니다. 새 토큰을 생성해야 하는 경우 이전 단계를 따르세요.
OAuth 토큰을 확인하려면 다음 URL을 브라우저에 붙여넣습니다.
```
https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token
```
다음과 같은 응답이 나타나야 합니다.
```
{
  "azp": <your_azp_value>,
  "aud": <your_aud_value>,
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "exp": "1694210968",
  "expires_in": "3334",
  "access_type": "online"
}
```
요청할 때 azp 또는 aud 필드는 필요하지 않습니다. azp 필드는 승인된 발표자의 client_id를 나타내고 aud 필드는 이 토큰의 대상을 식별하며, 이는 애플리케이션의 클라이언트 ID 중 하나와 같습니다.

참고: HTTP GET 요청을 실행하여 토큰을 확인할 수도 있습니다.
OAuth 토큰과 API 키를 수집합니다. Data Portability API를 호출하려면 이 정보가 필요합니다.

엔드포인트에 요청 전송

이 빠른 시작에서는 curl 명령어를 사용하여 Data Portability API 엔드포인트를 호출합니다. 이 명령어에는 이전에 수집한 OAuth 토큰과 API 키가 필요합니다.

Data Portability API를 호출하려면 다음 단계를 따르세요.

먼저 인증된 요청을 InitiatePortabilityArchive 엔드포인트로 전송합니다. 이 요청은 보관처리 작업을 시작합니다.

다음 curl 명령어를 실행합니다.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
이때 명령어의 각 값을 다음과 같이 바꿉니다.
- your_OAuth_token은 OAuth 토큰입니다.
경고: resources 매개변수에는 액세스 권한이 부여된 OAuth 범위만 포함되어야 합니다. 이 예에서는 myactivity.search만 부여되었습니다. 리소스 그룹을 추가하면 오류가 반환됩니다. 자세한 내용은 범위 제한을 참고하세요.

InitiatePortabilityArchive 요청은 job_id 및 accessType를 반환합니다. 작업 ID는 데이터 보관 파일의 상태를 검색하는 데 사용되며 액세스 유형에 따라 데이터에 대한 일회성 액세스 권한 또는 시간 기반 액세스 권한이 부여되었는지 결정됩니다. 이 빠른 시작에서는 일회성 액세스 권한이 있어야 합니다.
```
{
  'archiveJobId': '<your_job_id>'
  'accessType': 'ACCESS_TYPE_ONE_TIME'
}
```
유효한 OAuth 토큰을 제공하지 않으면 다음 오류 메시지가 반환됩니다.
```
Request had invalid authentication credentials. Expected OAuth 2.0 access
token, login cookie or other valid authentication credential. See
https://developers.google.com/identity/sign-in/web/devconsole-project.
```
그런 다음 GetPortabilityArchiveState 엔드포인트에 인증된 요청을 전송하여 보관처리 작업의 상태를 가져옵니다.

다음 curl 명령어를 실행합니다.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/your_job_id/portabilityArchiveState
```
이때 명령어의 각 값을 다음과 같이 바꿉니다.
- your_OAuth_token은 OAuth 토큰입니다.
- your_job_id는 InitiatePortabilityArchive 요청에서 반환된 작업 ID입니다.
응답은 작업의 상태를 기반으로 합니다. 작업이 완료되지 않은 경우 응답은 현재 상태를 제공합니다. 작업이 완료될 때까지 이 엔드포인트에 주기적으로 요청을 전송해야 합니다.
```
{
  "state": "IN_PROGRESS"
}
```
작업이 완료되면 응답에는 상태와 데이터 보관 파일을 다운로드하는 데 사용되는 서명된 URL 1개 이상이 포함됩니다.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
서명된 URL을 브라우저에 붙여넣어 데이터 보관 파일을 다운로드합니다. 보관 파일의 콘텐츠를 검토하여 예상되는 검색 활동 데이터가 포함되어 있는지 확인해야 합니다.

참고: 보관처리 작업을 완료하는 데 필요한 시간은 보관처리 파일의 크기에 따라 다릅니다. 최대 기간은 7일입니다.
참고: 응답에 FAILED 상태가 표시되면 RetryPortabilityArchive 메서드를 사용하여 내보내기를 다시 시도할 수 있습니다.

(선택사항) 이전 명령어를 반복하여 InitiatePortabilityArchive 엔드포인트에 인증된 요청을 전송합니다.

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

이때 명령어의 각 값을 다음과 같이 바꿉니다.

your_OAuth_token은 OAuth 토큰입니다.

응답은 이 사용자의 myactivity.search 리소스에 대한 일회성 동의가 소진되었음을 나타내야 합니다.

...
"error": {
    "code": 429,
    "message": "Requested resources have already been exported. Please call ResetAuthorization and re-obtain consent before trying again.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "{previous_job_ids}"
    "access_type": "ACCESS_TYPE_ONE_TIME"
...

ResetAuthorization 엔드포인트에 인증된 요청을 보냅니다. 이 요청은 사용자가 부여한 모든 OAuth 범위를 취소하고 이미 사용한 리소스 그룹에 대해 InitiatePortabilityArchive를 호출할 수 있도록 합니다.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset
```
이때 명령어의 각 값을 다음과 같이 바꿉니다.
- your_OAuth_token은 OAuth 토큰입니다.
이 명령어는 빈 응답을 반환합니다.

(선택사항) 승인을 재설정한 후 InitiatePortabilityArchive 엔드포인트에 다시 요청을 보냅니다. 이전에 사용한 것과 동일한 curl 명령어를 사용합니다.

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

이때 명령어의 각 값을 다음과 같이 바꿉니다.

your_OAuth_token은 OAuth 토큰입니다.

제공한 OAuth 토큰이 취소되었으므로 응답에 오류가 반환됩니다.

...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }