ฟีเจอร์ใหม่ของ Data Portability API กำลังเปิดตัวในขณะนี้ และจะพร้อมให้บริการแก่ทุกคนภายในวันที่ 20 กุมภาพันธ์ 2025

หน้านี้ได้รับการแปลโดย Cloud Translation API

ใช้ตัวกรองเวลากับคำขอ

ในการเริ่มต้นใช้งานอย่างรวดเร็วนี้ คุณจะได้รับโทเค็น OAuth สําหรับบัญชี และส่งคําขอไปยังปลายทาง Data Portability API โดยใช้การประทับเวลาเพื่อกรองข้อมูลที่ส่งออก

คู่มือเริ่มต้นฉบับย่อนี้ครอบคลุมวิธีใช้ Data Portability API กับการเข้าถึงตามเวลาและการใช้ตัวกรองเวลาสำหรับทรัพยากรที่รองรับ โปรดดูรายละเอียดเพิ่มเติมเกี่ยวกับการเข้าถึงข้อมูลผู้ใช้ตามเวลาได้ที่หัวข้อใช้การเข้าถึงตามเวลา

สิ่งที่คุณเรียนรู้

ในการเริ่มต้นใช้งานอย่างรวดเร็วนี้ คุณจะได้เรียนรู้วิธีต่อไปนี้

ส่งคําขอที่ตรวจสอบสิทธิ์ตามรอบไปยังInitiatePortabilityArchive อุปกรณ์ปลายทางเพื่อส่งออกเฉพาะข้อมูลใหม่นับตั้งแต่การส่งออกครั้งล่าสุด
ส่งคําขอที่ตรวจสอบสิทธิ์ไปยังปลายทาง InitiatePortabilityArchive เพื่อส่งออกเฉพาะข้อมูลจาก 6 เดือนที่ผ่านมา
ส่งคําขอที่ตรวจสอบสิทธิ์ไปยังปลายทาง InitiatePortabilityArchive เพื่อส่งออกเฉพาะข้อมูลจากระยะเวลาที่เฉพาะเจาะจง

ข้อกำหนดเบื้องต้น

หากต้องการเรียกใช้การเริ่มต้นใช้งานอย่างรวดเร็วนี้ คุณต้องดำเนินการดังนี้

ตรวจสอบว่า Data Portability API พร้อมให้บริการแก่ผู้ใช้ในพื้นที่ของคุณ ดูรายชื่อประเทศและภูมิภาคที่รองรับได้ที่คำถามที่พบบ่อยในหน้า "แชร์สำเนาข้อมูลกับบุคคลที่สาม"
ทําตามขั้นตอนการตั้งค่าสําหรับ Data Portability API ให้เสร็จสมบูรณ์
ทำตามขั้นตอนเพื่อกำหนดค่า OAuth สำหรับเว็บแอป JavaScript ในเวอร์ชันที่ใช้งานจริง คุณมักจะใช้ขั้นตอนอื่น เช่น ขั้นตอน OAuth สำหรับแอปพลิเคชันเว็บเซิร์ฟเวอร์ คู่มือเริ่มต้นฉบับย่อนี้ใช้ขั้นตอนของเว็บแอป JavaScript เพื่อให้เข้าใจง่าย
- เมื่อสร้างข้อมูลเข้าสู่ระบบการให้สิทธิ์ ให้จดรหัสไคลเอ็นต์ OAuth 2.0 และ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาต (เช่น https://google.com) คุณต้องใช้รหัสดังกล่าวในภายหลังในคู่มือเริ่มต้นใช้งาน
- เมื่อคุณกําหนดค่าขอบเขตสําหรับ Data Portability 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 สําหรับการเริ่มต้นใช้งานฉบับย่อนี้คือขอบเขตกิจกรรมการค้นหา คุณใช้ขอบเขตใดก็ได้ที่รองรับตัวกรองเวลา

คำเตือน: อย่าผสมผสานขอบเขตของ Data Portability API กับขอบเขตประเภทอื่นๆ ใช้ขอบเขตมากเกินไปในครั้งเดียว หรือรวมขอบเขตที่อนุญาตไว้ก่อนหน้านี้ เนื่องจากจะทำให้เกิดข้อผิดพลาด โปรดดูรายละเอียดที่หัวข้อข้อจำกัดของขอบเขต
วาง URL ในแถบที่อยู่ของเบราว์เซอร์ แล้วทำตามขั้นตอนในโฟลว์ OAuth ขั้นตอนนี้กำหนดให้คุณลงชื่อเข้าใช้บัญชีที่องค์กรเป็นเจ้าของหรือควบคุมอยู่ซึ่งคุณใช้สำหรับการเริ่มต้นใช้งานอย่างรวดเร็วนี้

บัญชีนี้เป็นบัญชีที่ให้ความยินยอมในขอบเขต OAuth หน้าจอขอความยินยอมควรมีลักษณะดังนี้ (ข้อความในหน้าจออาจแตกต่างจากข้อความในรูปภาพนี้)
เลือกขอบเขตที่จะให้สิทธิ์เข้าถึงและระยะเวลาในการแชร์สิทธิ์เข้าถึงข้อมูลของบัญชี (1 ครั้ง, 30 วัน หรือ 180 วัน) ในการเริ่มต้นใช้งานอย่างรวดเร็วนี้ ให้เลือก30 วัน (ตัวกรองเวลายังใช้ได้กับสิทธิ์เข้าถึงแบบครั้งเดียวด้วย)
หลังจากให้ความยินยอมและตัดสินใจระยะเวลาการเข้าถึงแล้ว ระบบควรส่งต่อคุณไปยัง 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 จะหมดอายุในอีก 1 ชั่วโมง หากต้องการสร้างโทเค็นใหม่ ให้ทำตามขั้นตอนก่อนหน้า
หากต้องการตรวจสอบโทเค็น 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 จะระบุกลุ่มเป้าหมายที่โทเค็นนี้มีไว้สำหรับ ซึ่งจะเท่ากับรหัสไคลเอ็นต์รายการใดรายการหนึ่งสำหรับแอปพลิเคชันของคุณ

หมายเหตุ: คุณยืนยันโทเค็นได้โดยส่งคำขอ HTTP GET
รวบรวมโทเค็น OAuth และคีย์ API คุณต้องใช้ข้อมูลเหล่านี้เพื่อเรียกใช้ Data Portability API

ส่งคําขอไปยังปลายทาง

ในบทแนะนำเริ่มต้นใช้งานนี้ คุณจะใช้คําสั่ง curl เพื่อเรียกใช้ปลายทาง Data Portability API พร้อมการประทับเวลาเพื่อกรองข้อมูลที่ส่งออก คําสั่งเหล่านี้ต้องใช้โทเค็น OAuth และคีย์ API ที่คุณรวบรวมไว้ก่อนหน้านี้

ข้อมูลจากการส่งออกครั้งล่าสุด

คุณสามารถใช้ตัวกรองเวลากับการเข้าถึงตามเวลาเพื่อส่งออกข้อมูลใหม่นับตั้งแต่การส่งออกครั้งล่าสุด เช่น ลองพิจารณาขอบเขต https://www.googleapis.com/auth/dataportability.myactivity.search

ขั้นแรก คุณต้องส่งคําขอที่ตรวจสอบสิทธิ์ไปยังปลายทาง 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 จะแสดงผล archiveJobId และ accessType ระบบจะใช้รหัสงานเพื่อดึงสถานะของที่เก็บถาวรของข้อมูล และประเภทการเข้าถึงจะกำหนดว่าคุณได้รับสิทธิ์เข้าถึงข้อมูลแบบครั้งเดียวหรือแบบตามเวลา สําหรับการเข้าถึงตามเวลา คุณจะเห็นข้อมูลต่อไปนี้
```
{
  "archiveJobId": "<your_job_id_1>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
หากระบุโทเค็น 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_1/portabilityArchiveState
```
ในคําสั่ง
- your_OAuth_token คือโทเค็น OAuth ของคุณ
- your_job_id_1 คือรหัสงานที่แสดงผลจากคำขอ InitiatePortabilityArchive
การตอบกลับจะอิงตามสถานะของงาน หากงานยังไม่เสร็จสมบูรณ์ การตอบกลับจะแสดงสถานะปัจจุบัน คุณควรส่งคำขอไปยังปลายทางนี้เป็นระยะๆ จนกว่างานจะเสร็จสมบูรณ์
```
{
  "state": "IN_PROGRESS"
}
```
หากงานเสร็จสมบูรณ์ การตอบกลับจะมีสถานะและ URL ที่มีการเซ็นชื่ออย่างน้อย 1 รายการที่ใช้ดาวน์โหลดที่เก็บถาวรของข้อมูล นอกจากนี้ยังมีช่อง export_time ที่แสดงการประทับเวลาเมื่อมีการเรียกใช้ InitiatePortabilityArchive ครั้งแรก
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}
```
วาง URL ที่ลงชื่อแล้วลงในเบราว์เซอร์เพื่อดาวน์โหลดไฟล์เก็บถาวรของข้อมูล คุณควรตรวจสอบเนื้อหาของไฟล์เก็บถาวรเพื่อให้แน่ใจว่ามีข้อมูลกิจกรรมการค้นหาที่คาดไว้

หมายเหตุ: ระยะเวลาที่ใช้ในการเก็บถาวรจนเสร็จสมบูรณ์จะขึ้นอยู่กับขนาดของไฟล์เก็บถาวร ระยะเวลาสูงสุดคือ 7 วัน

หากได้รับสถานะ FAILED ในการตอบกลับ คุณสามารถลองส่งออกอีกครั้งโดยใช้วิธีการ RetryPortabilityArchive
โปรดรออย่างน้อย 24 ชั่วโมงแล้วส่งคำขออีกครั้งไปยัง InitiatePortabilityArchive โดยใช้คำสั่งเดียวกับในขั้นตอนที่ 1 แต่ครั้งนี้ให้ใช้ export_time เป็น start_time
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": timestamp_of_first_initiate_request}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
หมายเหตุ: คุณปรับ start_time ให้ซ้อนทับกับ export_time เล็กน้อยได้เพื่อให้แน่ใจว่าข้อมูลที่สร้างขึ้นระหว่างคำขอจะรวมอยู่ในการส่งออก

สําหรับการเข้าถึงตามเวลา ผลลัพธ์ที่ได้จะเป็นดังนี้
```
{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
ทำขั้นตอนที่ 2 ซ้ำเพื่อส่งคำขอที่ตรวจสอบสิทธิ์ไปยังปลายทาง GetPortabilityArchiveState เพื่อดึงข้อมูลสถานะของงานเก็บถาวร (โดยใช้ <your_job_id_2>)

เมื่องานเสร็จสมบูรณ์แล้ว การตอบกลับจะเป็นดังนี้

  {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

ยืนยันว่าข้อมูลในการส่งออกครั้งที่ 2 มีเฉพาะข้อมูลที่สร้างขึ้นใหม่หลังจากการส่งออกครั้งแรก

ข้อมูลจาก 6 เดือนที่ผ่านมา

นอกจากนี้ คุณยังใช้ตัวกรองเวลาเพื่อส่งออกเฉพาะข้อมูลล่าสุดแทนการส่งออกทั้งชุดได้ด้วย

สมมติว่าวันนี้เป็นวัน 2024-10-01 และคุณต้องการส่งออกข้อมูลในช่วง 6 เดือนที่ผ่านมา ก่อนอื่น ให้ส่งคําขอที่ตรวจสอบสิทธิ์ไปยังปลายทาง InitiatePortabilityArchive ที่มี start_time เป็น "2024-04-01T00:00:00Z"

เรียกใช้คำสั่ง curl ต่อไปนี้
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2024-04-01T00:00:00Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
สําหรับการเข้าถึงตามเวลา ผลลัพธ์ที่ได้จะเป็นดังนี้
```
{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
ส่งคําขอไปยังปลายทาง 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/job_id_1/portabilityArchiveState
```
เมื่องานเสร็จสมบูรณ์แล้ว การตอบกลับจะเป็นดังนี้
```
{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}
```
โปรดทราบว่า start_time คือ start_time ที่ระบุไว้ในขั้นตอนที่ 1 และ export_time คือการประทับเวลาเมื่อมีการเรียกใช้ InitiatePortabilityArchive ในขั้นตอนที่ 1
ตรวจสอบว่าการส่งออกมีเฉพาะข้อมูลจาก 6 เดือนที่ผ่านมา

ข้อมูลจากระยะเวลาหนึ่งๆ

คุณสามารถใช้ตัวกรองเวลาเพื่อส่งออกข้อมูลจากช่วงวันที่ที่เฉพาะเจาะจง เช่น ข้อมูลจากปี 2023 เท่านั้น

ก่อนอื่น ให้ส่งคําขอที่ตรวจสอบสิทธิ์ไปยังปลายทาง InitiatePortabilityArchive โดยมี start_time เป็น "2023-01-01T00:00:00Z" และ end_time เป็น "2023-12-31T23:59:59Z"

เรียกใช้คำสั่ง curl ต่อไปนี้
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
สําหรับการเข้าถึงตามเวลา ผลลัพธ์ที่ได้จะเป็นดังนี้
```
{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
ส่งคําขอไปยังปลายทาง 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/job_id_1/portabilityArchiveState
```
เมื่องานเสร็จสมบูรณ์แล้ว การตอบกลับจะเป็นดังนี้
```
{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}
```
โปรดทราบว่า start_time คือ start_time ที่ระบุไว้ในขั้นตอนที่ 1 และ export_time เท่ากับ end_time ที่ระบุไว้ในขั้นตอนที่ 1
ตรวจสอบว่าการส่งออกมีเฉพาะข้อมูลจากปี 2023 เท่านั้น

ขอบเขตที่รองรับ

ขอบเขตต่อไปนี้รองรับตัวกรองเวลา

https://www.googleapis.com/auth/dataportability.myactivity.youtube
https://www.googleapis.com/auth/dataportability.myactivity.maps
https://www.googleapis.com/auth/dataportability.myactivity.search
https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
https://www.googleapis.com/auth/dataportability.myactivity.shopping
https://www.googleapis.com/auth/dataportability.myactivity.play
https://www.googleapis.com/auth/dataportability.chrome.history

ข้อควรระวัง: คำขอที่กรองตามเวลาซึ่งรวมขอบเขตที่รองรับและไม่รองรับเข้าด้วยกันจะทำให้เกิดข้อผิดพลาด INVALID_ARGUMENT ที่ระบุว่า The requested resources do not support time filters