Package google.digitalassetlinks.v1

ดัชนี

คำชี้แจง

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

คำสั่งทั้งหมดที่แสดงผลโดย API นี้จัดทำขึ้นในนามของเนื้อหาดิจิทัล (เช่น เว็บไซต์หรือแอป Android) เกี่ยวกับเนื้อหาดิจิทัลอื่นๆ แต่ละคำสั่งประกอบด้วยชิ้นงานแหล่งที่มา ชิ้นงานเป้าหมาย และความสัมพันธ์อย่างน้อย 1 รายการ

ความสัมพันธ์จะอธิบายความสัมพันธ์ระหว่างเนื้อหาทั้ง 2 รายการตามที่เนื้อหาแหล่งที่มาอ้างสิทธิ์ ตัวอย่างของความสัมพันธ์ดังกล่าวคือการมอบสิทธิ์หรือสิทธิ์ต่างๆ

รายการ

rpc List(ListRequest) returns (ListResponse)

ดึงรายการของคำสั่งทั้งหมดจากแหล่งที่มาที่ระบุ ซึ่งตรงกับเป้าหมายและสตริงคำสั่งที่ระบุ

API นี้รับประกันว่าข้อความทั้งหมดที่มีชิ้นงานแหล่งที่มาที่ปลอดภัย เช่น เว็บไซต์ HTTPS หรือแอป Android นั้นสร้างขึ้นอย่างปลอดภัยโดยเจ้าของเนื้อหาเหล่านั้น ดังที่อธิบายไว้ในข้อกำหนดทางเทคนิคเกี่ยวกับการออกแบบลิงก์เนื้อหาดิจิทัล (Digital Asset Links) โดยเฉพาะอย่างยิ่ง คุณควรพิจารณาสิ่งนี้สำหรับเว็บไซต์ที่ไม่ปลอดภัย (กล่าวคือ URL ขึ้นต้นด้วย http:// แทนที่จะเป็น https://) การรับประกันนี้ไม่สามารถดำเนินการได้

คำสั่ง List มีประโยชน์มากที่สุดในกรณีที่ไคลเอ็นต์ API ต้องการทราบวิธีที่เนื้อหา 2 รายการเกี่ยวข้องกัน หรือแจกแจงความสัมพันธ์ทั้งหมดจากเนื้อหาแหล่งที่มาบางรายการ ตัวอย่างเช่น ฟีเจอร์ที่ช่วยให้ผู้ใช้ไปยังรายการที่เกี่ยวข้องได้ เมื่อแอปบนอุปกรณ์เคลื่อนที่ทำงานบนอุปกรณ์ ฟีเจอร์นี้จะช่วยให้สามารถไปยังเว็บไซต์หรือโปรไฟล์ Google+ ที่เกี่ยวข้องได้อย่างง่ายดาย

AndroidAppAsset

อธิบายชิ้นงานแอป Android

ชื่อช่อง ประเภท คำอธิบาย
package_name string โดยปกติแล้วเนื้อหาแอป Android จะระบุด้วยชื่อแพ็กเกจ Java ตัวอย่างเช่น แอป Google Maps ใช้ชื่อแพ็กเกจ com.google.android.apps.maps ต้องระบุ
certificate CertificateInfo

เนื่องจากไม่มีการบังคับใช้ที่ไม่ซ้ำกันสำหรับชื่อแพ็กเกจทั่วโลก เราจึงกำหนดให้ต้องมีใบรับรองที่ลงนามด้วย ซึ่งเมื่อใช้ร่วมกับชื่อแพ็กเกจจะระบุแอปที่ไม่ซ้ำกัน

คีย์ Signing ของบางแอปจะมีการหมุนเวียน ดังนั้นอาจมีการลงชื่อโดยใช้คีย์ต่างๆ เมื่อเวลาผ่านไป เราถือว่าข้อมูลเหล่านี้เป็นเนื้อหาที่แตกต่างกันเนื่องจากเราใช้ (ชื่อแพ็กเกจ ใบรับรอง) เป็นรหัสที่ไม่ซ้ำกัน โดยปกตินี้จะไม่ก่อให้เกิดปัญหาใดๆ เนื่องจากแอปทั้ง 2 เวอร์ชันจะมีข้อความที่เหมือนกันหรือคล้ายกัน อย่างไรก็ตาม เนื้อหาอื่นๆ ที่ระบุข้อความเกี่ยวกับแอปจะต้องได้รับการอัปเดตเมื่อมีการหมุนเวียนคีย์

(โปรดทราบว่าไวยากรณ์สำหรับการเผยแพร่และการค้นหาข้อความจะมีน้ำตาลสังเคราะห์เพื่อให้คุณระบุแอปที่ใบรับรองหลายใบรู้จักได้อย่างง่ายดาย) ต้องระบุ

CertificateInfo

อธิบายใบรับรอง X509

ชื่อช่อง ประเภท คำอธิบาย
sha256_fingerprint string

ลายนิ้วมือ SHA-265 ตัวพิมพ์ใหญ่ของใบรับรอง ใบรับรอง PEM จะรับรูปแบบต่อไปนี้ได้

$ keytool -printcert -file $CERTFILE | grep SHA256:
SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
    42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5

หรือแบบนี้

$ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
    16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5

ในตัวอย่างนี้ เนื้อหาของช่องนี้จะเป็น 14:6D:E9:83:C5:73: 06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF: 44:E5

หากเครื่องมือเหล่านี้ไม่พร้อมใช้งาน คุณสามารถแปลงใบรับรอง PEM เป็นรูปแบบ DER โดยคำนวณแฮช SHA-256 ของสตริงนั้นและแสดงผลลัพธ์เป็นสตริงฐานสิบหก (ซึ่งก็คือเลขฐานสิบหกตัวพิมพ์ใหญ่ของอ็อกเท็ตแต่ละตัว โดยคั่นด้วยโคลอน)

ชิ้นงาน

ระบุเนื้อหาโดยไม่ซ้ำกัน

เนื้อหาดิจิทัลคือเอนทิตีออนไลน์ที่ระบุตัวบุคคลนั้นได้และเข้าถึงได้ ซึ่งโดยปกติแล้วจะให้บริการหรือเนื้อหาบางอย่าง ตัวอย่างเนื้อหา ได้แก่ เว็บไซต์, แอป Android, ฟีด Twitter และ Plus Pages

ชื่อช่อง ประเภท คำอธิบาย
ฟิลด์สหภาพ มีเพียงรายการใดรายการหนึ่งต่อไปนี้
web WebAsset กำหนดว่าเนื้อหานี้เป็นเนื้อหาเว็บหรือไม่
android_app AndroidAppAsset กำหนดว่าเป็นชิ้นงานแอป Android หรือไม่

CheckRequest

ข้อความที่ใช้ตรวจสอบการมีอยู่ของลิงก์ชิ้นงานที่เฉพาะเจาะจง

ชื่อช่อง ประเภท คำอธิบาย
source Asset แหล่งที่มาที่โฮสต์รายการใบแจ้งยอด ใช้เพื่อกำหนดเส้นทางการเรียก Check() ไปยังต้นทางที่เหมาะสม
relation string

สตริงการค้นหาสำหรับความสัมพันธ์

เราจะระบุความสัมพันธ์กับสตริงของรูปแบบ <kind>/<detail> โดยที่ <kind> ต้องเป็นหนึ่งในชุดหมวดหมู่วัตถุประสงค์ที่กำหนดไว้ล่วงหน้า และ <detail> คือสตริงอักขระที่เป็นตัวอักษรและตัวเลขคละกันรูปแบบอิสระที่อธิบายถึงกรณีการใช้งานเฉพาะของคำสั่ง

โปรดดูเอกสารประกอบของ API สำหรับรายการความสัมพันธ์ที่รองรับในปัจจุบัน

ในการค้นหาจับคู่ลิงก์เนื้อหา ทั้งสตริงที่เกี่ยวข้องของการค้นหาและลิงก์เนื้อหาต้องตรงกันทุกประการ

เช่น การค้นหาที่มีความสัมพันธ์ delegate_permission/common.handle_all_urls ตรงกับลิงก์ชิ้นงานที่มีความสัมพันธ์ delegate_permission/common.handle_all_urls
target Asset เนื้อหาเป้าหมายของใบแจ้งยอด

CheckResponse

ข้อความตอบกลับสำหรับการโทร CheckAssetLinks

ชื่อช่อง ประเภท คำอธิบาย
linked bool ตั้งค่าเป็น "จริง" หากเนื้อหาที่ระบุในคำขอลิงก์ตามความเกี่ยวข้องที่ระบุไว้ในคำขอ ต้องระบุ
max_age Duration ตั้งแต่เวลาที่แสดง การตอบกลับควรถือว่านานกว่าระยะเวลาใดหากจำเป็นต้องอัปเดตเพิ่มเติม ต้องระบุ
debug_string string

ข้อความที่มนุษย์อ่านได้ซึ่งมีข้อมูลเพื่อช่วยให้ผู้ใช้ปลายทางเข้าใจ ทำซ้ำ และแก้ไขข้อบกพร่องของผลลัพธ์

ข้อความจะเป็นภาษาอังกฤษและขณะนี้เราไม่ได้วางแผนที่จะให้บริการแปล

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

ListRequest

ข้อความที่ใช้ขอคำชี้แจงทั้งหมดที่ทราบซึ่งมีแหล่งที่มาและความเกี่ยวข้องที่ระบุ

ชื่อช่อง ประเภท คำอธิบาย
source Asset แหล่งที่มาที่โฮสต์รายการใบแจ้งยอด ใช้เพื่อส่งคำขอ List() ไปยังแหล่งที่มาที่ถูกต้อง ต้องระบุ
relation string

ใช้เฉพาะการเชื่อมโยงที่ตรงกับความสัมพันธ์ที่ระบุ

ดูคำอธิบายโดยละเอียดของสตริงที่เกี่ยวข้องในข้อความ Statement

ข้อความค้นหาตรงกับคำสั่ง ข้อใดข้อหนึ่งต่อไปนี้ต้องเป็นจริง

  • ทั้งสตริงความสัมพันธ์ของคำสั่งและสตริงความสัมพันธ์ของคำสั่งตรงกันทั้งหมด หรือ
  • สตริงความสัมพันธ์ของการค้นหาว่างเปล่าหรือขาดหายไป

เช่น การค้นหาที่มีความสัมพันธ์ delegate_permission/common.handle_all_urls ตรงกับลิงก์ชิ้นงานที่มีความสัมพันธ์ delegate_permission/common.handle_all_urls

ListResponse

ข้อความตอบกลับสำหรับการเรียกรายการ

ชื่อช่อง ประเภท คำอธิบาย
statements Statement รายการข้อความที่ตรงกันทั้งหมดที่พบ
max_age Duration ตั้งแต่เวลาที่แสดง การตอบกลับควรถือว่านานกว่าระยะเวลาใดหากจำเป็นต้องอัปเดตเพิ่มเติม ต้องระบุ
debug_string string

ข้อความที่มนุษย์อ่านได้ซึ่งมีข้อมูลเพื่อช่วยให้ผู้ใช้ปลายทางเข้าใจ ทำซ้ำ และแก้ไขข้อบกพร่องของผลลัพธ์

ข้อความจะเป็นภาษาอังกฤษและขณะนี้เราไม่ได้วางแผนที่จะให้บริการแปล

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

คำสั่ง

อธิบายข้อความที่เชื่อถือได้เกี่ยวกับความสัมพันธ์ระหว่างชิ้นงานแหล่งที่มากับเนื้อหาเป้าหมาย

ใบแจ้งยอดจะสร้างขึ้นโดยเนื้อหาแหล่งที่มาเสมอ ไม่ว่าจะโดยตรงหรือด้วยการมอบสิทธิ์ไปยังรายการใบแจ้งยอดที่จัดเก็บไว้ที่อื่น

ดูคำจำกัดความของข้อความและชิ้นงานโดยละเอียดได้ที่หน้า Landing Page สําหรับเอกสาร API

ชื่อช่อง ประเภท คำอธิบาย
source Asset ทุกใบแจ้งยอดจะมีเนื้อหาแหล่งที่มา ต้องระบุ
relation string

ความเกี่ยวข้องจะระบุถึงการใช้คำสั่งตามที่เจ้าของเนื้อหาแหล่งที่มาต้องการ (กล่าวคือ บุคคลหรือนิติบุคคลที่ออกคำชี้แจง) ทุกถ้อยคำที่สมบูรณ์มีความเกี่ยวข้อง

เราจะระบุความสัมพันธ์กับสตริงของรูปแบบ <kind>/<detail> โดยที่ <kind> ต้องเป็นหนึ่งในชุดหมวดหมู่วัตถุประสงค์ที่กำหนดไว้ล่วงหน้า และ <detail> คือสตริงอักขระที่เป็นตัวอักษรและตัวเลขคละกันรูปแบบอิสระที่อธิบายถึงกรณีการใช้งานเฉพาะของคำสั่ง

โปรดดูเอกสารประกอบของ API สำหรับรายการความสัมพันธ์ที่รองรับในปัจจุบัน

ตัวอย่าง: delegate_permission/common.handle_all_urls REQUIRED
target Asset ทุกใบแจ้งยอดจะมีเนื้อหาเป้าหมาย ต้องระบุ

WebAsset

อธิบายเนื้อหาเว็บ

ชื่อช่อง ประเภท คำอธิบาย
site string

เนื้อหาในเว็บจะระบุโดย URL ที่มีเฉพาะรูปแบบ ชื่อโฮสต์ และส่วนพอร์ต รูปแบบคือ

http[s]://<hostname>[:<port>]

ชื่อโฮสต์ต้องเป็นแบบเต็ม โดยต้องลงท้ายด้วยจุดเดียว (".")

เฉพาะรูปแบบ "http" และ "https" เท่านั้นในปัจจุบัน

หมายเลขพอร์ตจะระบุเป็นเลขทศนิยม และต้องละเว้นหากใช้หมายเลขพอร์ตมาตรฐาน เช่น 80 สำหรับ http และ 443 สำหรับ https

เราเรียก URL ที่จำกัดนี้ว่า "ไซต์" URL ทั้งหมดที่ใช้รูปแบบ ชื่อโฮสต์ และพอร์ตเดียวกันถือว่าเป็นส่วนหนึ่งของเว็บไซต์ ดังนั้นจึงเป็นของเนื้อหาเว็บ

ตัวอย่างเช่น เนื้อหาที่มีเว็บไซต์ https://www.google.com มี URL เหล่านี้ทั้งหมด

  • https://www.google.com/
  • https://www.google.com:443/
  • https://www.google.com/foo
  • https://www.google.com/foo?bar
  • https://www.google.com/foo#bar
  • https://user@password:www.google.com/

แต่ไม่มี URL เหล่านี้:

  • http://www.google.com/ (สคีมไม่ถูกต้อง)
  • https://google.com/ (ชื่อโฮสต์ไม่ตรงกัน)
  • https://www.google.com:444/ (พอร์ตไม่ตรงกัน) ต้องระบุ