Эта страница переведена с помощью Cloud Translation API.

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

В этом кратком руководстве вы получите токен OAuth для своей учетной записи и отправите запросы к конечным точкам 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:

Создайте 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 или обе области.
Предупреждение. Не смешивайте области API переносимости данных с другими типами областей и не включайте ранее предоставленные области, поскольку это приведет к ошибкам. Подробности см. в разделе Ограничения области действия .
Вставьте URL-адрес в адресную строку браузера и следуйте инструкциям в потоке OAuth. Для этого процесса вам потребуется войти в учетную запись, принадлежащую или контролируемую вашей организацией, которую вы используете для этого краткого руководства.
Это учетная запись, которая дает согласие на области действия OAuth. Экран согласия должен выглядеть следующим образом (текст на вашем экране может отличаться от текста на этом изображении):
После предоставления согласия вы должны быть перенаправлены на 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> — это строка, представляющая токен.
Важно! Срок действия вашего токена доступа OAuth истекает через один час. Если вам нужно создать новый токен, выполните предыдущие шаги.
Чтобы проверить токен 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"
}
```
Примечание. Вы также можете проверить токен, выполнив запрос HTTP GET.
Соберите свой токен OAuth и ключ API . Они нужны вам для выполнения вызовов API переносимости данных.

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

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

Чтобы вызвать 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 . Этот идентификатор задания используется для получения состояния архива данных.
```
{
  "archiveJobId": "<your_job_id>"
}
```
Если вы не предоставите действительный токен 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 .
Ответ зависит от состояния задания. Если задание не завершено, в ответе указывается текущее состояние. Вам следует периодически отправлять запросы к этой конечной точке, пока задание не будет завершено.
```
{
  "state": "IN_PROGRESS"
}
```
Если задание выполнено, ответ содержит состояние и один или несколько подписанных URL-адресов, которые используются для загрузки архива данных.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
Вставьте подписанный URL-адрес в свой браузер, чтобы загрузить архив данных. Вам следует проверить содержимое архива, чтобы убедиться, что он содержит ожидаемые данные о поисковой активности.
Примечание. Время, необходимое для выполнения задания архивирования, зависит от размера архива. Максимальная продолжительность — семь дней.
Примечание. Если в ответе вы получили состояние 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": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}
```
Отправьте аутентифицированный запрос в конечную точку 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"
  }