Применяйте временные фильтры к вашим запросам

В этом кратком руководстве вы получите токен OAuth для своей учетной записи и отправите запросы к конечным точкам API переносимости данных, используя временные метки для фильтрации экспортированных данных.

В этом кратком руководстве рассказывается, как использовать API переносимости данных с доступом по времени и применять временные фильтры для поддерживаемых ресурсов. Дополнительные сведения о доступе к пользовательским данным на основе времени см. в разделе Использование доступа на основе времени .

Что вы узнаете

Из этого краткого руководства вы узнаете, как:

  • Отправляйте повторяющиеся запросы с проверкой подлинности в конечную точку InitiatePortabilityArchive , чтобы экспортировать только новые данные с момента последнего экспорта.
  • Отправьте проверенный запрос в конечную точку InitiatePortabilityArchive чтобы экспортировать данные только за последние 6 месяцев.
  • Отправьте проверенный запрос в конечную точку InitiatePortabilityArchive , чтобы экспортировать данные только за определенный период времени.

Предварительные условия

Чтобы запустить это краткое руководство, вам необходимо:

  • Убедитесь, что API переносимости данных доступен пользователям в вашем регионе. Список поддерживаемых стран и регионов см. в разделе «Общие вопросы» на странице «Отправка копии своих данных третьему лицу».
  • Выполните шаги по настройке API переносимости данных.
  • Следуйте инструкциям по настройке OAuth для веб-приложений JavaScript . В рабочей среде обычно используется другой поток, например поток OAuth для приложений веб-сервера . Для простоты в этом кратком руководстве используется поток веб-приложения JavaScript.
    • При создании учетных данных для авторизации запишите свой идентификатор клиента OAuth 2.0 и URI авторизованного перенаправления (например, https://google.com). Они понадобятся вам позже в кратком руководстве.
    • При настройке областей для API переносимости данных обратите внимание, что в этом кратком руководстве используется группа ресурсов myactivity.search : https://www.googleapis.com/auth/dataportability.myactivity.search.
    • Когда вы выбираете период времени, в течение которого вы хотите разрешить доступ, вам следует выбрать 30 дней , чтобы протестировать фильтрацию времени с доступом на основе времени. (Временные фильтры также работают при одноразовом доступе).
  • Получите токен OAuth.
  • Получите доступ к учетной записи, принадлежащей или контролируемой вашей организацией. Данные о поисковой активности этого аккаунта экспортируются в этом кратком руководстве.

Получить токен OAuth

В этом кратком руководстве вы отправляете запрос авторизации для получения токена OAuth с помощью URL-адреса. Этот процесс использует поток веб-приложений 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.
    • redirect_uri — ваш авторизованный URI перенаправления; например, https://google.com.

    Обратите внимание, что область действия, используемая в URL-адресе для этого краткого руководства, — это область действия поиска. Вы можете использовать любые области, поддерживающие временные фильтры.

  2. Вставьте URL-адрес в адресную строку браузера и следуйте инструкциям в потоке OAuth. Для этого процесса вам необходимо войти в учетную запись, принадлежащую или контролируемую вашей организацией, которую вы используете для этого краткого руководства.

    Это учетная запись, которая дает согласие на области действия OAuth. Экран согласия должен выглядеть следующим образом (текст на вашем экране может отличаться от текста на этом изображении):

    Экран согласия, на котором пользователь соглашается разрешить доступ к данным поисковой активности.

  3. Выберите области предоставления доступа и продолжительность предоставления доступа к данным учетной записи (один раз, 30 дней или 180 дней). Для этого краткого руководства выберите 30 дней . (Временные фильтры также работают при одноразовом доступе.)

  4. После предоставления согласия и определения продолжительности доступа вы должны быть перенаправлены на URI перенаправления — https://google.com. URL-адрес, созданный в адресной строке, включает токен доступа OAuth.

    Например, если учетная запись пользователя предоставляет доступ OAuth к области dataportability.myactivity.search , сгенерированный 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 определяет аудиторию, для которой предназначен этот токен, которая будет равна одному из идентификаторов клиента вашего приложения.

  6. Соберите свой токен OAuth и ключ API . Они нужны вам для выполнения вызовов API переносимости данных.

Отправлять запросы на конечные точки

В этом кратком руководстве вы используете команды Curl для вызова конечных точек 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 . Идентификатор задания используется для получения состояния архива данных, а тип доступа определяет, был ли вам предоставлен однократный или временной доступ к данным. Для доступа по времени вы увидите:

    {
  "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 .

    Ответ зависит от состояния задания. Если задание не завершено, в ответе указывается текущее состояние. Вам следует периодически отправлять запросы к этой конечной точке, пока задание не будет завершено.

    {
  "state": "IN_PROGRESS"
}

    Если задание выполнено, ответ содержит состояние и один или несколько подписанных URL-адресов, которые используются для загрузки архива данных. Существует также поле export_time , которое представляет временную метку первого вызова InitiatePortabilityArchive . 

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

    Вставьте подписанный URL-адрес в свой браузер, чтобы загрузить архив данных. Вам следует проверить содержимое архива, чтобы убедиться, что он содержит ожидаемые данные о поисковой активности.

    Если вы получили в ответ состояние FAILED , вы можете повторить экспорт, используя метод RetryPortabilityArchive .

  3. Подождите не менее 24 часов, а затем сделайте еще один запрос к InitiatePortabilityArchive используя ту же команду, что и на шаге 1, но на этот раз используйте значение 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 месяцев. Сначала вы отправляете аутентифицированный запрос в конечную точку InitiatePortabilityArchive с start_time «2024-04-01T00:00:00Z».

    Запустите следующую команду 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 — это start_time указанное на шаге 1, а export_time — это отметка времени, когда на шаге 1 был выполнен вызов InitiatePortabilityArchive .

  3. Убедитесь, что экспорт содержит данные только за последние шесть месяцев.

Данные за определенный период времени

Вы можете использовать временные фильтры для экспорта данных за определенный диапазон дат, например данные только за 2023 год.

  1. Сначала вы отправляете аутентифицированный запрос в конечную точку InitiatePortabilityArchive с start_time «2023-01-01T00:00:00Z» и end_time «2023-12-31T23:59:59Z».

    Запустите следующую команду 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 — это start_time указанное на шаге 1, а время export_time равно времени end_time указанному на шаге 1.

  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

Внимание: запросы с фильтрацией по времени, в которых смешиваются поддерживаемые и неподдерживаемые области, приводят к ошибке INVALID_ARGUMENT , в которой говорится, The requested resources do not support time filters .