ใช้การเข้าถึงตามเวลา

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

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

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

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

  • ส่งคำขอที่ตรวจสอบสิทธิ์แล้วไปยังปลายทาง InitiatePortabilityArchive โดยระบุโทเค็น OAuth ที่ถูกต้อง การตอบกลับควรมี job_id ที่ถูกต้อง
  • ส่งคำขอที่ตรวจสอบสิทธิ์แล้วไปยังปลายทาง GetPortabilityArchiveState การตอบกลับควรมีสถานะงานที่ถูกต้อง และ URL ที่เซ็นชื่อเมื่องานเสร็จสมบูรณ์
  • ส่งคำขอที่ตรวจสอบสิทธิ์แล้วซึ่งมีโทเค็น OAuth ที่ถูกต้องไปยังปลายทาง InitiatePortabilityArchive อีกครั้งโดยใช้ข้อมูลเข้าสู่ระบบเดียวกัน ซึ่งจะแสดงข้อผิดพลาด FAILED_PRECONDITION เมื่อส่งคำขอภายใน 24 ชั่วโมงนับจากคำขอแรก

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

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

รับโทเค็น OAuth

ในการเริ่มต้นใช้งานอย่างรวดเร็วนี้ คุณจะส่งคําขอการให้สิทธิ์เพื่อรับโทเค็น OAuth โดยใช้ URL กระบวนการนี้ใช้ขั้นตอนสําหรับเว็บแอปฝั่งเซิร์ฟเวอร์ ขั้นตอนนี้จะสร้างโทเค็นรีเฟรชที่คุณสามารถใช้สำหรับการส่งออกครั้งต่อๆ ไปได้

วิธีรับโทเค็น OAuth

  1. เขียน URL ดังต่อไปนี้

    https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=code&
access_type=offline&
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 หรือทั้ง 2 ขอบเขตก็ได้

  2. วาง URL ในแถบที่อยู่ของเบราว์เซอร์ แล้วทำตามขั้นตอนในโฟลว์ OAuth ขั้นตอนนี้กำหนดให้คุณลงชื่อเข้าใช้บัญชีที่องค์กรเป็นเจ้าของหรือควบคุมอยู่ซึ่งคุณใช้สำหรับการเริ่มต้นใช้งานอย่างรวดเร็วนี้

    บัญชีนี้เป็นบัญชีที่ให้ความยินยอมในขอบเขต OAuth หน้าจอขอความยินยอมควรมีลักษณะดังนี้ (ข้อความในหน้าจออาจแตกต่างจากข้อความในรูปภาพนี้)

    หน้าจอขอความยินยอมที่ผู้ใช้ยินยอมให้เข้าถึงข้อมูลกิจกรรมการค้นหา

  3. เลือกขอบเขตที่จะให้สิทธิ์เข้าถึงและระยะเวลาในการแชร์สิทธิ์เข้าถึงข้อมูลของบัญชี (1 ครั้ง, 30 วัน หรือ 180 วัน) ในการเริ่มต้นใช้งานอย่างรวดเร็วนี้ ให้เลือก30 วัน

  4. หลังจากให้ความยินยอมและตัดสินใจเกี่ยวกับระยะเวลาการเข้าถึงแล้ว ระบบควรส่งต่อคุณไปยัง URI เปลี่ยนเส้นทาง https://google.com โดย URL ที่สร้างขึ้นในแถบที่อยู่จะมีรหัสการให้สิทธิ์ที่คุณนำไปแลกเป็นโทเค็น OAuth ในขั้นตอนถัดไป

    ตัวอย่างเช่น หากบัญชีผู้ใช้ให้สิทธิ์เข้าถึง OAuth แก่ขอบเขต dataportability.myactivity.search URL ที่สร้างขึ้นจะมีลักษณะดังนี้

    https://google.com/#state=developer-specified-value&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

  5. หากต้องการเปลี่ยนรหัสการให้สิทธิ์เป็นโทเค็นการเข้าถึง ให้เรียกใช้ปลายทางโทเค็น OAuth ด้วยข้อมูลต่อไปนี้

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'

    การตอบกลับควรมีลักษณะดังนี้

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}

    ใน URL your_OAuth_token คือสตริงที่แสดงถึงโทเค็น

    ช่อง refresh_token_expires_in จะแสดงเป็นวินาทีและจะระบุว่าผู้ใช้เลือกการเข้าถึง 30 วัน (2592000 วินาที) หรือ 180 วัน (15552000 วินาที) หากแอปมีสถานะการเผยแพร่เป็นการทดสอบ คุณจะมีสิทธิ์เข้าถึงเป็นเวลา 7 วัน (604800 วินาที) แทน โดยไม่คำนึงถึงการเลือกของผู้ใช้

  6. หากต้องการตรวจสอบโทเค็น 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 จะระบุกลุ่มเป้าหมายที่โทเค็นนี้มีไว้สำหรับ ซึ่งจะเท่ากับรหัสไคลเอ็นต์รายการใดรายการหนึ่งสำหรับแอปพลิเคชันของคุณ

  7. รวบรวมโทเค็น OAuth และคีย์ API คุณต้องใช้ข้อมูลเหล่านี้เพื่อเรียกใช้ Data Portability API

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

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

วิธีเรียกใช้ Data Portability API

  1. ขั้นแรก ให้ส่งคำขอที่มีการตรวจสอบสิทธิ์ไปยังปลายทาง 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 ของคุณ

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

    {
  "archiveJobId": "<your_job_id>"
  "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.

  2. จากนั้นส่งคำขอที่ตรวจสอบสิทธิ์ไปยังปลายทาง 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 ที่มีการเซ็นชื่ออย่างน้อย 1 รายการที่ใช้ดาวน์โหลดที่เก็บถาวรของข้อมูล

    {
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}

    วาง URL ที่ลงนามแล้วลงในเบราว์เซอร์เพื่อดาวน์โหลดไฟล์เก็บถาวรของข้อมูล คุณควรตรวจสอบเนื้อหาของไฟล์เก็บถาวรเพื่อให้แน่ใจว่ามีข้อมูลกิจกรรมการค้นหาที่คาดไว้

    หากได้รับสถานะ FAILED ในการตอบกลับ คุณสามารถลองส่งออกอีกครั้งโดยใช้วิธีการ RetryPortabilityArchive

  3. พิมพ์คำสั่งก่อนหน้าซ้ำเพื่อส่งคำขอที่ตรวจสอบสิทธิ์แล้วไปยังปลายทาง 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": "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}"
...

  4. หลังจากผ่านไป 24 ชั่วโมง คุณจะขอการส่งออกใหม่ได้ แต่ก่อนอื่นคุณต้องแลกโทเค็นการรีเฟรชเป็นโทเค็นการเข้าถึงใหม่

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'

    การตอบกลับควรมีลักษณะดังนี้

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}

    หากผู้ใช้ต่ออายุสิทธิ์เข้าถึง เวลาหมดอายุใหม่จะแสดงในช่อง refresh_token_expires_in

    คุณสามารถใช้โทเค็นการเข้าถึงใหม่เพื่อทําตามขั้นตอน InitiatePortabilityArchive และ GetPortabilityArchiveState ซ้ำได้