Zacznij korzystać z interfejsu Data Portability API

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

W tym krótkim wprowadzeniu dowiesz się, jak używać interfejsu Data Portability API do jednorazowego uzyskania dostępu do danych użytkownika. Aby uzyskać stały dostęp do danych użytkownika, zapoznaj się z artykułem Używanie dostępu czasowego. Aby dowiedzieć się, jak stosować filtry czasowe w prośbach, przeczytaj artykuł Stosowanie filtrów czasowych.

Czego się nauczysz

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

Prześlij uwierzytelnione żądanie do punktu końcowego InitiatePortabilityArchive, podając prawidłowy token OAuth. Odpowiedź powinna zawierać prawidłowy obiekt 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 ważnym tokenem OAuth do punktu końcowego InitiatePortabilityArchive po raz drugi, używając tych samych danych logowania. Zwraca to błąd RESOURCE_EXHAUSTED i ma na celu podkreślenie znaczenia punktu końcowego ResetAuthorization.
Wyślij uwierzytelnione żądanie do punktu końcowego ResetAuthorization. Ta prośba powoduje unieważnienie wszystkich przyznanych przez użytkownika zakresów protokołu OAuth.
(Opcjonalnie) Wyślij żądanie do punktu końcowego InitiatePortabilityArchive, używając tego samego tokena OAuth, którego użyto wcześniej. Po zresetowaniu autoryzacji żądanie powinno się nie powieść.

Wymagania wstępne

Aby uruchomić to krótkie wprowadzenie:

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 danych innej firmie”.
Wykonaj czynności konfiguracyjne interfejsu Data Portability API.
Wykonaj czynności opisane w sekcji Konfigurowanie OAuth w przypadku aplikacji internetowych w języku JavaScript. W wersji produkcyjnej zwykle używasz innego sposobu, na przykład ścieżki OAuth w aplikacjach serwera WWW. W tym krótkim wprowadzeniu używamy ścieżki aplikacji internetowej w języku JavaScript ze względu na jej prostotę.
- Podczas tworzenia danych uwierzytelniających zanotuj identyfikator klienta OAuth 2.0 i autoryzowany identyfikator URI przekierowania (np. https://google.com). Będą one potrzebne w dalszej części samouczka.
- Podczas konfigurowania zakresów interfejsu Data Portability API pamiętaj, że ten samouczek używa myactivity.search grupy zasobów: https://www.googleapis.com/auth/dataportability.myactivity.search.
- Gdy wybierzesz czas, przez jaki chcesz zezwolić na dostęp, ten samouczek użyje dostępu jednorazowego.
Uzyskaj token OAuth.
uzyskać dostęp do konta należącego do organizacji lub kontrolowanego przez nią. W tym samouczku dane o aktywności związanej z wyszukiwaniem na tym koncie są eksportowane.

Uzyskiwanie tokena OAuth

W tym krótkim wprowadzeniu wyślesz żądanie autoryzacji, aby uzyskać token OAuth, używając adresu URL. Ten proces wykorzystuje proces dotyczący aplikacji internetowych w JavaScript. Ten proces 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 tego jest przepływ danych w aplikacji internetowych po stronie serwera.

Aby uzyskać token OAuth:

Utwórz adres URL podobny do tego:
```
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
```
W adresie URL:
- client_id to identyfikator klienta OAuth.
- redirect_uri to autoryzowany identyfikator URI przekierowania, np. https://google.com.
Zwróć uwagę, że zakres użyty w adresie URL tego krótkiego wprowadzenia to zakres aktywności wyszukiwania. Możesz też użyć zakresu aktywności w YouTube lub obu zakresów.

Ostrzeżenie: nie mieszaj zakresów interfejsu Data Portability API z innymi zakresami, nie używaj zbyt wielu zakresów naraz ani nie uwzględniaj wcześniej przyznanych zakresów, ponieważ może to spowodować błędy. Szczegółowe informacje znajdziesz w ograniczeniach zakresu.
Wklej adres URL na pasku adresu przeglądarki i postępuj zgodnie z instrukcjami procesu OAuth. W tym procesie musisz zalogować się na konto należące do Twojej organizacji lub przez nią kontrolowane, którego używasz w tym samouczku.

To jest konto, które wyraża zgodę na zakresy OAuth. Ekran zgody powinien wyglądać tak (tekst na Twoim ekranie może się różnić od tego na obrazku):
Wybierz zakresy, do których chcesz przyznać dostęp, oraz czas udostępniania dostępu do danych na koncie (raz, 30 dni lub 180 dni). Na potrzeby tego krótkiego wprowadzenia wybierz Tylko raz.
Po wyrażeniu zgody i wybraniu czasu dostępu powinieneś zostać przekierowany do adresu URI przekierowania https://google.com. Adres URL wygenerowany w 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
```
W adresie URL ciąg your_OAuth_token reprezentuje token.

Ważne: token dostępu OAuth wygasa po 1 godzinie. Jeśli musisz wygenerować nowy token, wykonaj poprzednie czynności.
Aby zweryfikować token OAuth, wklej ten adres 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"
}
```
Aby wysyłać żądania, nie musisz używać pól azp ani aud. Pole azp reprezentuje client_id autoryzowanej aplikacji prezentującej token, a pole aud identyfikuje odbiorcę, dla którego jest przeznaczony dany token. Będzie on równy jednemu z identyfikatorów klienta Twojej aplikacji.

Uwaga: token możesz też zweryfikować, wysyłając żądanie HTTP GET.
Uzyskaj token OAuth i klucz interfejsu API. Potrzebujesz ich do wywoływania 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ą wcześniej zebranego tokenu OAuth i klucza interfejsu API.

Aby wywołać interfejs Data Portability API:

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

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 tym poleceniu:
- your_OAuth_token to Twój token OAuth.
Uwaga: parametr resources powinien zawierać tylko te zakresy OAuth, do których przyznano dostęp. W tym przykładzie przyznano tylko uprawnienie myactivity.search. Jeśli uwzględnisz dodatkowe grupy zasobów, zwrócony zostanie błąd. Więcej informacji znajdziesz w sekcji Ograniczenia zakresu
.
Prośba InitiatePortabilityArchive zwraca job_id i accessType. Identyfikator zadania służy do pobierania stanu archiwum danych, a typ dostępu określa, czy masz jednorazowy czy czasowy dostęp do danych. Na potrzeby tego samouczka powinieneś mieć dostęp jednorazowy.
```
{
  'archiveJobId': '<your_job_id>'
  'accessType': 'ACCESS_TYPE_ONE_TIME'
}
```
Jeśli nie podasz prawidłowego tokena OAuth, zwróci 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 tym poleceniu:
- your_OAuth_token to Twój token OAuth.
- your_job_id to identyfikator zadania zwrócony w odpowiedzi na żądanie InitiatePortabilityArchive.
Odpowiedź zależy od stanu zadania. Jeśli zadanie nie zostało ukończone, odpowiedź zawiera jego bieżący stan. Do tego punktu końcowego należy okresowo wysyłać żądania, aż do zakończenia zadania.
```
{
  "state": "IN_PROGRESS"
}
```
Jeśli zadanie zostało ukończone, odpowiedź zawiera stan i co najmniej 1 adres URL podpisany cyfrowo, który służy do pobrania archiwum danych.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
Aby pobrać archiwum danych, wklej podpisany adres URL w przeglądarce. Sprawdź zawartość archiwum, aby się upewnić, że zawiera ono oczekiwane dane o aktywności wyszukiwania.

Uwaga: czas potrzebny na wykonanie zadania archiwizacji zależy od rozmiaru archiwum. Maksymalny czas trwania to 7 dni.
Uwaga: jeśli w odpowiedzi pojawi się stan FAILED, możesz ponownie spróbować wyeksportować dane, używając 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 tym poleceniu:

your_OAuth_token to Twój token OAuth.

Odpowiedź powinna wskazywać, że jednorazowa zgoda na korzystanie z zasosobu myactivity.search została wykorzystana przez tego użytkownika.

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

Wyślij uwierzytelnione żądanie do punktu końcowego ResetAuthorization. To żądanie cofa wszystkie zakresy OAuth przyznane przez użytkownika i umożliwia wywołanie funkcji InitiatePortabilityArchive w przypadku grupy zasobów, której już używasz.
```
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 tym 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, którego używałeś(-aś) 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 tym poleceniu:

your_OAuth_token to Twój token OAuth.

Odpowiedź powinna zwrócić błąd, ponieważ podany token OAuth został cofnięty.

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