Ta strona została przetłumaczona przez Cloud Translation API.

Zacznij korzystać z interfejsu Data Portability API

W tym krótkim wprowadzeniu uzyskasz token OAuth dla swojego konta i wyślesz żądania do punktów końcowych interfejsu Data Portability API.

Czego się uczysz

Z tego krótkiego wprowadzenia dowiesz się, jak:

Wyślij uwierzytelnione żądanie do punktu końcowego InitiatePortabilityArchive, podając prawidłowy token OAuth. Odpowiedź powinna zawierać prawidłowy atrybut job_id.
Wyślij uwierzytelnione żądanie do punktu końcowego GetPortabilityArchiveState. Odpowiedź powinna zawierać prawidłowy stan zadania, a po jego zakończeniu – podpisany adres URL.
(Opcjonalnie) Wyślij uwierzytelnione żądanie z prawidłowym tokenem OAuth do punktu końcowego InitiatePortabilityArchive ponownie, korzystając z tych samych danych logowania. Zwraca to błąd RESOURCE_EXHAUSTED i ma podkreślić znaczenie punktu końcowego ResetAuthorization.
Wyślij uwierzytelnione żądanie do punktu końcowego ResetAuthorization. To żądanie anuluje wszystkie zakresy OAuth przyznane przez użytkowników.
(Opcjonalnie) Wyślij żądanie do punktu końcowego InitiatePortabilityArchive przy użyciu tego samego tokena OAuth, który został użyty wcześniej. Po zresetowaniu autoryzacji żądanie powinno zakończyć się niepowodzeniem.

Wymagania wstępne

Aby uruchomić to krótkie wprowadzenie, musisz:

Sprawdź, czy interfejs Data Portability API jest dostępny dla użytkowników w Twojej lokalizacji. Listę obsługiwanych krajów i regionów znajdziesz w sekcji Najczęstsze pytania na stronie „Udostępnianie kopii swoich danych firmom zewnętrznym”.
Wykonaj instrukcje konfiguracji interfejsu Data Portability API.
Postępuj zgodnie z instrukcjami konfigurowania protokołu OAuth na potrzeby aplikacji internetowych z JavaScriptem. W środowisku produkcyjnym zwykle stosuje się inny przepływ, taki jak proces OAuth dla aplikacji serwera WWW. Dla uproszczenia w tym krótkim wprowadzeniu wykorzystaliśmy przepływ aplikacji internetowej w języku JavaScript.
- Podczas tworzenia danych logowania zanotuj identyfikator klienta OAuth 2.0 i autoryzowany identyfikator przekierowania (np. https://google.com). Będą one potrzebne w dalszej części krótkiego wprowadzenia.
- Podczas konfigurowania zakresów na potrzeby interfejsu Data Portability API zwróć uwagę na to, że w tym krótkim wprowadzeniu używana jest grupa zasobów myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
Uzyskaj token OAuth.
Uzyskaj dostęp do konta należącego do Twojej organizacji lub przez nią kontrolowane. Dane o aktywności związanej z wyszukiwaniem na tym koncie są eksportowane z tego krótkiego wprowadzenia.

Uzyskiwanie tokena OAuth

W ramach tego krótkiego wprowadzenia wyślij żądanie autoryzacji, aby uzyskać token OAuth, używając adresu URL. Proces ten jest używany w przypadku aplikacji internetowych JavaScript. Ten przepływ nie zwraca tokena odświeżania.

W przypadku aplikacji produkcyjnej zwykle używa się procesu OAuth do uzyskiwania tokena odświeżania, który można wykorzystać do generowania tokenów dostępu na żądanie. Przykładem może być procedura w przypadku aplikacji internetowych po stronie serwera.

Aby uzyskać token OAuth:

Utwórz adres URL podobny do poniższego.
```
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&
include_granted_scopes=true&
state=developer-specified-value
```
W adresie URL:
- client_id to identyfikator Twojego klienta OAuth.
- redirect_uri to Twój autoryzowany identyfikator URI przekierowania, np. https://google.com.
Zwróć uwagę, że zakres użyty w adresie URL w tym krótkim wprowadzeniu to zakres aktywności związanej z wyszukiwaniem. Możesz też korzystać z zakresu aktywności w YouTube lub obu zakresów.
Wklej ten adres w pasku adresu przeglądarki i postępuj zgodnie z instrukcją OAuth. Aby skorzystać z tej procedury, musisz zalogować się na konto należące do organizacji, której używasz w tym krótkim wprowadzeniu, lub przez nią kontrolowane.

Jest to konto, które wyraża zgodę na zakresy protokołu OAuth. Ekran zgody powinien wyglądać tak (tekst na ekranie może się różnić od tekstu na tym obrazie):
Gdy wyrazisz zgodę, przekierujemy Cię na stronę identyfikatora URI przekierowania – https://google.com. URL wygenerowany na pasku adresu zawiera token dostępu OAuth.

Jeśli na przykład konto użytkownika przyznaje dostęp OAuth do zakresu dataportability.myactivity.search, wygenerowany adres URL będzie wyglądał tak:
```
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
```
Ciąg <twój_token_OAuth> w adresie URL reprezentuje ten token.

Ważne: token dostępu OAuth wygasa za godzinę. Jeśli musisz wygenerować nowy token, wykonaj czynności opisane powyżej.

Aby sprawdzić poprawność tokena OAuth, wklej ten URL w przeglądarce:

https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token

Odpowiedź powinna wyglądać tak:

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

Uzyskaj token OAuth i klucz interfejsu API. Są one niezbędne do wykonywania wywołań interfejsu Data Portability API.

Wysyłanie żądań do punktów końcowych

W tym krótkim wprowadzeniu używasz poleceń curl do wywoływania punktów końcowych interfejsu Data Portability API. Te polecenia wymagają tokena OAuth i klucza interfejsu API, które udało Ci się wcześniej uzyskać.

Aby wywołać interfejs Data Portability API:

Najpierw wysyłasz uwierzytelnione żądanie do punktu końcowego InitiatePortabilityArchive. To żądanie rozpoczyna zadanie archiwizacji.

Uruchom to polecenie 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
```
W poleceniu:
- your_OAuth_token to Twój token OAuth.
UWAGA: parametr resources powinien zawierać tylko zakresy OAuth, które mają przyznany dostęp. W tym przykładzie przyznano tylko myactivity.search. Jeśli dołączysz dodatkowe grupy zasobów, zostanie zwrócony błąd.

Żądanie InitiatePortabilityArchive zwraca wartość job_id. Ten identyfikator zadania służy do pobierania stanu archiwum danych.
```
{
  "archiveJobId": "<your_job_id>"
}
```
Jeśli nie podasz prawidłowego tokena OAuth, wyświetli się ten komunikat o błędzie:
```
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.
```
Następnie wysyłasz uwierzytelnione żądanie do punktu końcowego GetPortabilityArchiveState, aby pobrać stan zadania archiwizacji.

Uruchom to polecenie 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
```
W poleceniu:
- your_OAuth_token to Twój token OAuth.
- your_job_id to identyfikator zadania zwrócony przez żądanie InitiatePortabilityArchive.
Odpowiedź zależy od state zadania. Jeśli zadanie nie jest ukończone, w odpowiedzi podany jest bieżący stan. Do tego punktu końcowego należy okresowo wysyłać żądania, dopóki zadanie nie zostanie ukończone.
```
{
  "state": "IN_PROGRESS"
}
```
Jeśli zadanie zostało ukończone, odpowiedź zawiera stan i co najmniej 1 podpisany adres URL używany do pobrania archiwum danych.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
Wklej podpisany adres URL w przeglądarce, aby pobrać archiwum danych. Należy sprawdzić zawartość archiwum, aby upewnić się, że zawiera ono dane o oczekiwanej aktywności związanej z wyszukiwaniem.

Uwaga: czas potrzebny na ukończenie zadania archiwizacji zależy od jego rozmiaru. Maksymalny czas trwania to 7 dni.
Uwaga: jeśli w odpowiedzi otrzymasz stan FAILED, możesz spróbować wyeksportować dane po raz kolejny, korzystając z metody RetryPortabilityArchive.

(Opcjonalnie) Powtórz poprzednie polecenie, aby wysłać uwierzytelnione żądanie do punktu końcowego 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

W poleceniu:

your_OAuth_token to Twój token OAuth.

Odpowiedź powinna informować, że jednorazowa zgoda na zasób myactivity.search została wyczerpana w przypadku tego użytkownika.

...
  "error":
    {
      "code": 429,
  "message": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

Wyślij uwierzytelnione żądanie do punktu końcowego ResetAuthorization. To żądanie anuluje wszystkie zakresy OAuth przyznane przez użytkowników i pozwala wywołać InitiatePortabilityArchive w przypadku grupy zasobów, która została już przez Ciebie używana.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset
```
W poleceniu:
- your_OAuth_token to Twój token OAuth.
To polecenie zwraca pustą odpowiedź.

(Opcjonalnie) Po zresetowaniu autoryzacji wyślij kolejne żądanie do punktu końcowego InitiatePortabilityArchive. Użyj tego samego polecenia curl co wcześniej.

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

W poleceniu:

your_OAuth_token to Twój token OAuth.

Odpowiedź powinna zwrócić błąd, ponieważ podany przez Ciebie token OAuth został unieważniony.

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