Начните использовать API переносимости данных

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

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

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

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

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

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

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

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

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

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

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

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

  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, которые вы собрали ранее.

Чтобы вызвать 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_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.

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

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

  4. Отправьте аутентифицированный запрос в конечную точку 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.

    Эта команда возвращает пустой ответ.

  5. (Необязательно) После сброса авторизации отправьте еще один запрос в конечную точку 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"
  }