Используйте доступ по времени

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

В этом кратком руководстве рассказывается, как использовать API переносимости данных для доступа к пользовательским данным на основе времени. Для получения информации о однократном доступе к пользовательским данным см. раздел «Начало использования API переносимости данных» . Чтобы узнать, как применить временные фильтры к вашему запросу, см. раздел «Применение временных фильтров» .

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

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

  • Отправьте аутентифицированный запрос в конечную точку InitiatePortabilityArchive , предоставив действительный токен OAuth. Ответ должен содержать действительный job_id .
  • Отправьте аутентифицированный запрос в конечную точку GetPortabilityArchiveState . Ответ должен содержать допустимое состояние задания, а после завершения задания — подписанный URL-адрес.
  • Отправьте проверенный запрос с действительным токеном OAuth в конечную точку InitiatePortabilityArchive во второй раз, используя те же учетные данные. Это возвращает ошибку FAILED_PRECONDITION , если запрос сделан в течение 24 часов после первоначального запроса.

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

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

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

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

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

Чтобы получить токен OAuth:

  1. Создайте URL-адрес, подобный следующему.

    https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=code&
access_type=offline&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value

    В URL-адресе:

    • client_id — ваш идентификатор клиента OAuth.
    • redirect_uri — ваш авторизованный URI перенаправления; например, https://google.com.

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

  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&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

  5. Чтобы обменять код авторизации на токен доступа, вызовите конечную точку токена oauth с помощью:

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'

    Ответ должен выглядеть так:

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}

    В URL-адресе your_OAuth_token — это строка, представляющая токен.

    refresh_token_expires_in указано в секундах и отражает, выбрал ли пользователь 30 дней (2592000 секунд) или 180 дней (15552000 секунд) доступа. Если ваше приложение имеет статус публикации «Тестирование» , вместо этого у вас есть 7 дней (604 800 секунд) доступа независимо от выбора пользователя.

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

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

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

В этом кратком руководстве вы используете команды Curl для вызова конечных точек API переносимости данных. Для этих команд требуется токен OAuth и ключ API, которые вы собрали ранее.

Чтобы вызвать API переносимости данных:

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

    {
  "archiveJobId": "<your_job_id>"
  "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/portabilityArchiveState

    В команде:

    • your_OAuth_token — это ваш токен OAuth.
    • your_job_id — это идентификатор задания, возвращаемый запросом InitiatePortabilityArchive .

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

    {
  "state": "IN_PROGRESS"
}

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

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

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

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

  3. Повторите предыдущую команду, чтобы отправить аутентифицированный запрос в конечную точку 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. You can initiate another export after #{timestamp_after_24hrs}.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "#{previous_job_ids}"
    "access_type": "ACCESS_TYPE_TIME_BASED"
    "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
...

  4. Через 24 часа вы можете запросить новый экспорт, но сначала вам необходимо обменять токен обновления на новый токен доступа. 

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'

    Ответ должен выглядеть так: 

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}

    Если пользователь продлевает доступ, новое время истечения срока действия отображается в refresh_token_expires_in .

    Вы можете использовать новый токен доступа для повторения шагов InitiatePortabilityArchive и GetPortabilityArchiveState .