เริ่มใช้ Data Portability API

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

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

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

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

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

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

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

รับโทเค็น OAuth

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

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

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

  1. เขียน 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 สําหรับการเริ่มต้นใช้งานฉบับย่อนี้คือขอบเขตกิจกรรมการค้นหา นอกจากนี้ คุณยังใช้ขอบเขตกิจกรรม YouTube หรือทั้ง 2 ขอบเขตก็ได้

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

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

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

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

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

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

  6. รวบรวมโทเค็น 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_ONE_TIME'
}

    หากระบุโทเค็น 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 ที่ลงชื่อแล้วลงในเบราว์เซอร์เพื่อดาวน์โหลดไฟล์เก็บถาวรของข้อมูล คุณควรตรวจสอบเนื้อหาของไฟล์เก็บถาวรเพื่อให้แน่ใจว่ามีข้อมูลกิจกรรมการค้นหาที่คาดไว้

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

  4. ส่งคำขอที่ตรวจสอบสิทธิ์แล้วไปยังปลายทาง ResetAuthorization คำขอนี้จะเพิกถอนขอบเขต OAuth ที่ผู้ใช้ให้สิทธิ์ทั้งหมด และให้คุณเรียกใช้ InitiatePortabilityArchive สำหรับกลุ่มทรัพยากรที่คุณใช้ไปแล้วได้

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset

    ในคําสั่ง

    • your_OAuth_token คือโทเค็น OAuth ของคุณ

    คำสั่งนี้จะแสดงผลลัพธ์ที่ว่างเปล่า

  5. (ไม่บังคับ) หลังจากรีเซ็ตการให้สิทธิ์แล้ว ให้ส่งคําขออีกรายการไปยังปลายทาง 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 ของคุณ

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

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