Korzystanie z dostępu zależnego od czasu

W ramach tego krótkiego wprowadzenia uzyskasz token OAuth dla swojego konta i będziesz wysyłać żądania cykliczne do punktów końcowych interfejsu Data Portability API.

Z tego krótkiego wprowadzenia dowiesz się, jak używać interfejsu Data Portability API do uzyskiwania dostępu do danych użytkownika na podstawie czasu. Informacje o jednorazowym dostępie do danych użytkownika znajdziesz w artykule Rozpoczynanie korzystania z interfejsu Data Portability API. Aby dowiedzieć się, jak zastosować filtry czasowe do prośby, 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.
Po raz drugi wyślij uwierzytelnione żądanie z ważnym tokenem OAuth do punktu końcowego InitiatePortabilityArchive, używając tych samych danych logowania. Jeśli żądanie zostanie wysłane w ciągu 24 godzin od pierwszego żądania, zwróci ono błąd FAILED_PRECONDITION.

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.
- Wybierając czas dostępu, wybierz 30 dni, aby przetestować dostęp na określony czas.
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 tekstu na tym obrazie):
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 30 dni.
Po wyrażeniu zgody i określeniu czasu trwania 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. W przypadku dostępu na podstawie czasu zobaczysz:
```
{
  "archiveJobId": "<your_job_id>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
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.

Jeśli w odpowiedzi otrzymasz stan FAILED, możesz ponownie spróbować wyeksportować dane, używając metody RetryPortabilityArchive.

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 zasób myactivity.search został już wyeksportowany, oraz zawierać sygnaturę czasową, która pozwoli Ci spróbować ponownie.

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