요청에 시간 필터 적용하기

이 빠른 시작에서는 계정의 OAuth 토큰을 가져오고 타임스탬프를 사용하여 Data Portability API 엔드포인트에 요청을 전송하여 내보낸 데이터를 필터링합니다.

이 빠른 시작에서는 시간 기반 액세스와 함께 Data Portability API를 사용하고 지원되는 리소스에 시간 필터를 적용하는 방법을 설명합니다. 사용자 데이터에 대한 시간 기반 액세스에 관한 자세한 내용은 시간 기반 액세스 사용을 참고하세요.

학습 내용

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

  • InitiatePortabilityArchive 엔드포인트에 반복 인증된 요청을 전송하여 마지막 내보내기 이후의 새 데이터만 내보냅니다.
  • InitiatePortabilityArchive 엔드포인트에 인증된 요청을 전송하여 지난 6개월 동안의 데이터만 내보냅니다.
  • 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)을 사용합니다.
    • 액세스를 허용할 시간을 선택할 때 시간 기반 액세스로 시간 필터링을 테스트하려면 30일을 선택해야 합니다. 시간 필터는 일회성 액세스에도 작동합니다.
  • OAuth 토큰을 가져옵니다.
  • 조직에서 소유하거나 관리하는 계정에 대한 액세스 권한을 얻습니다. 이 빠른 시작에서는 이 계정의 검색 활동 데이터를 내보냅니다.

OAuth 토큰 가져오기

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

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

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

  1. 다음과 같은 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에 사용된 범위는 검색 활동 범위입니다. 시간 필터를 지원하는 모든 범위를 사용할 수 있습니다.

  2. 브라우저의 주소 표시줄에 URL을 붙여넣고 OAuth 흐름의 단계를 따릅니다. 이 흐름을 사용하려면 이 빠른 시작에 사용하는 조직에서 소유하거나 관리하는 계정으로 로그인해야 합니다.

    OAuth 범위에 동의하는 계정입니다. 동의 화면은 다음과 같이 표시됩니다(화면의 텍스트는 이 이미지의 텍스트와 다를 수 있음).

    사용자가 검색 활동 데이터에 대한 액세스를 허용하는 데 동의하는 동의 화면

  3. 액세스 권한을 부여할 범위와 계정 데이터에 대한 액세스 권한을 공유할 기간 (한 번, 30일 또는 180일)을 선택합니다. 이 빠른 시작에서는 30일을 선택합니다. 시간 필터는 일회성 액세스에도 작동합니다.

  4. 동의하고 액세스 기간을 결정하면 리디렉션 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는 토큰을 나타내는 문자열입니다.

  5. 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 중 하나와 같습니다.

  6. OAuth 토큰과 API 키를 수집합니다. Data Portability API를 호출하려면 이 정보가 필요합니다.

엔드포인트에 요청 전송

이 빠른 시작에서는 curl 명령어를 사용하여 타임스탬프가 있는 Data Portability API 엔드포인트를 호출하여 내보낸 데이터를 필터링합니다.이러한 명령어에는 이전에 수집한 OAuth 토큰과 API 키가 필요합니다.

마지막 내보내기의 데이터

시간 기반 액세스와 함께 시간 필터를 사용하여 마지막으로 내보낸 이후의 새 데이터를 내보낼 수 있습니다. 예를 들어 범위 https://www.googleapis.com/auth/dataportability.myactivity.search을 고려해 보세요.

  1. 먼저 인증된 요청을 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 토큰입니다.

    InitiatePortabilityArchive 요청은 archiveJobId 및 accessType를 반환합니다. 작업 ID는 데이터 보관 파일의 상태를 검색하는 데 사용되며 액세스 유형에 따라 데이터에 대한 일회성 액세스 권한 또는 시간 기반 액세스 권한이 부여되었는지 결정됩니다. 시간 기반 액세스의 경우 다음이 표시됩니다.

    {
  "archiveJobId": "<your_job_id_1>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

    유효한 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.

  2. 그런 다음 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_1/portabilityArchiveState

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

    • your_OAuth_token은 OAuth 토큰입니다.
    • your_job_id_1는 InitiatePortabilityArchive 요청에서 반환된 작업 ID입니다.

    응답은 작업의 상태를 기반으로 합니다. 작업이 완료되지 않은 경우 응답은 현재 상태를 제공합니다. 작업이 완료될 때까지 이 엔드포인트에 주기적으로 요청을 전송해야 합니다.

    {
  "state": "IN_PROGRESS"
}

    작업이 완료되면 응답에는 상태와 데이터 보관 파일을 다운로드하는 데 사용되는 서명된 URL 1개 이상이 포함됩니다. InitiatePortabilityArchive를 처음 호출한 타임스탬프를 나타내는 export_time 필드도 있습니다.

    {
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}

    서명된 URL을 브라우저에 붙여넣어 데이터 보관 파일을 다운로드합니다. 보관 파일의 콘텐츠를 검토하여 예상되는 검색 활동 데이터가 포함되어 있는지 확인해야 합니다.

    응답에 FAILED 상태가 표시되면 RetryPortabilityArchive 메서드를 사용하여 내보내기를 다시 시도할 수 있습니다.

  3. 24시간 이상 기다린 후 1단계와 동일한 명령어를 사용하여 InitiatePortabilityArchive에 다시 요청하지만 이번에는 export_time를 start_time로 사용합니다.

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

    시간 기반 액세스의 경우 다음이 반환됩니다.

    {
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

  4. 2단계를 반복하여 GetPortabilityArchiveState 엔드포인트에 인증된 요청을 전송하여 보관처리 작업의 상태를 가져옵니다 (<your_job_id_2> 사용).

  5. 작업이 완료되면 응답은 다음과 같습니다.

      {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

  6. 두 번째 내보내기의 데이터에 첫 번째 내보내기 후에 생성된 새 데이터만 포함되어 있는지 확인합니다.

지난 6개월 동안의 데이터

시간 필터를 사용하여 전체 자료 대신 최근 데이터만 내보낼 수도 있습니다.

  1. 오늘 날짜가 2024-10-01이고 지난 6개월 동안의 데이터를 내보내려 한다고 가정해 보겠습니다. 먼저 start_time이 '2024-04-01T00:00:00Z'인 인증된 요청을 InitiatePortabilityArchive 엔드포인트로 전송합니다.

    다음 curl 명령어를 실행합니다.

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

    시간 기반 액세스의 경우 다음이 반환됩니다.

    {
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

  2. 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/job_id_1/portabilityArchiveState

    작업이 완료되면 응답은 다음과 같습니다.

    {
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}

    start_time는 1단계에서 지정된 start_time이고 export_time는 1단계에서 InitiatePortabilityArchive 호출이 이루어진 시점의 타임스탬프입니다.

  3. 내보낸 파일에 지난 6개월 동안의 데이터만 포함되어 있는지 확인합니다.

특정 기간의 데이터

시간 필터를 사용하여 2023년 데이터만 내보내는 등 특정 기간의 데이터를 내보낼 수 있습니다.

  1. 먼저 start_time이 '2023-01-01T00:00:00Z'이고 end_time이 '2023-12-31T23:59:59Z'인 인증된 요청을 InitiatePortabilityArchive 엔드포인트로 전송합니다.

    다음 curl 명령어를 실행합니다.

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    시간 기반 액세스의 경우 다음이 반환됩니다.

    {
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

  2. 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/job_id_1/portabilityArchiveState

    작업이 완료되면 응답은 다음과 같습니다.

    {
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

    start_time는 1단계에서 지정된 start_time이고 export_time는 1단계에서 제공된 end_time와 같습니다.

  3. 내보낸 파일에 2023년 데이터만 포함되어 있는지 확인합니다.

지원되는 범위

다음 범위에서 시간 필터를 지원합니다.

  • https://www.googleapis.com/auth/dataportability.myactivity.youtube
  • https://www.googleapis.com/auth/dataportability.myactivity.maps
  • https://www.googleapis.com/auth/dataportability.myactivity.search
  • https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
  • https://www.googleapis.com/auth/dataportability.myactivity.shopping
  • https://www.googleapis.com/auth/dataportability.myactivity.play
  • https://www.googleapis.com/auth/dataportability.chrome.history

주의: 지원되는 범위와 지원되지 않는 범위가 혼합된 시간 필터링된 요청은 The requested resources do not support time filters라고 표시된 INVALID_ARGUMENT 오류를 유발합니다.