เอกสารอ้างอิง API ของไลบรารีไคลเอ็นต์การตรวจวัดระยะไกลของ Rust

หน้านี้อธิบายประเภท วิธีการ และการจัดการข้อผิดพลาดในไลบรารี libsdv_telemetry_rust_wrapper

อินเทอร์เฟซ TelemetryServiceHolder

อินเทอร์เฟซหลักสำหรับไคลเอ็นต์คือโครงสร้าง TelemetryServiceHolder อินเทอร์เฟซนี้มีชุดวิธีการทั้งหมดสำหรับการจัดการการเชื่อมต่อบริการ การกำหนดค่าเมตริก และรายงานข้อมูล

การจัดการวงจรการให้บริการ

เมธอดเหล่านี้จะสร้างและสิ้นสุดการเชื่อมต่อกับบริการการวัดและส่งข้อมูลพื้นฐาน

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

เมธอดแบบคงที่ที่เรียกแฮนเดิลที่ปลอดภัยแบบเธรดไปยังบริการการวัดและส่งข้อมูล นี่คือการเรียกที่บล็อกซึ่งจะรอจนกว่าบริการ Binder การวัดและส่งข้อมูลจะพร้อม บริการการวัดและส่งข้อมูลรองรับอินสแตนซ์เดียวของ TelemetryServiceHolder การเรียกเมธอดนี้มากกว่า 1 ครั้งจะทำให้เกิดลักษณะการทำงานที่ไม่คาดคิดหรือไม่ได้กำหนดไว้

TelemetryServiceHolder ใช้ลักษณะ Send และ Sync ซึ่งหมายความว่าสามารถแชร์ได้อย่างปลอดภัยในหลายๆ เธรด เช่น โดยการห่อไว้ในอินสแตนซ์ของ Arc วิธีการส่วนใหญ่ของ TelemetryServiceHolder เป็นแบบ async และใช้พร้อมกันได้

init

pub async fn init(
    &self,
    misc_status_callback: impl Fn(TelemetryServiceStatus) + Send + Sync + 'static,
    report_ready_callback: impl Fn(ReportInfo) + Send + Sync + 'static,
) -> TelemetryResult<()>

เริ่มต้นบริการโดยการลงทะเบียนการเรียกกลับแบบไม่พร้อมกัน เรียกใช้เมธอดนี้ 1 ครั้งหลังจากได้รับ TelemetryServiceHolder และก่อนการโต้ตอบอื่นๆ

เสร็จสิ้น

pub fn finish(&self) -> TelemetryResult<()>

ปิดการเชื่อมต่อบริการอย่างราบรื่น ล้าง Listener ที่ลงทะเบียน และล้างทรัพยากรที่เชื่อมโยง เรียกใช้เมธอดนี้ 1 ครั้งเมื่อแอปสิ้นสุด

การจัดการการกำหนดค่าเมตริก

เมธอดแบบไม่พร้อมกันเหล่านี้จะจัดการคําจํากัดความและสถานะของการกําหนดค่าการเก็บรวบรวมข้อมูล

บริการการวัดและส่งข้อมูลจะรักษาการกำหนดค่าไว้ใน 2 สถานะ ได้แก่

• ไม่ได้ใช้งาน: ระบบจะตรวจสอบการกำหนดค่าและจัดเก็บไว้ในดิสก์ แต่จะไม่ ใช้สำหรับการเก็บรวบรวมข้อมูล
• ใช้งานอยู่: การกำหนดค่าจะรวบรวมข้อมูล และคอมโพเนนต์ (ทริกเกอร์ ผู้เผยแพร่โฆษณา เป็นต้น) จะใช้งานอยู่

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

add_metrics_config

pub async fn add_metrics_config(&self, serialized_config: &[u8]) -> TelemetryResult<String>

เพิ่มการกำหนดค่าเมตริกใหม่ลงในบริการ การกำหนดค่าต้อง ระบุเป็นอาร์เรย์ไบต์ที่ซีเรียลไลซ์ การกำหนดค่าที่เพิ่มจะไม่มีการใช้งานโดยค่าเริ่มต้น

activate_metrics_config

pub async fn activate_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>

เปิดใช้งานการกำหนดค่าเมตริกที่เพิ่ม (หรือปิดใช้งาน) ไว้ก่อนหน้านี้ โดยเริ่มการเก็บรวบรวมข้อมูลและการรายงาน

deactivate_metrics_config

pub async fn deactivate_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>

หยุดการเก็บรวบรวมข้อมูลและการรายงานสําหรับการกําหนดค่าเมตริกที่ใช้งานอยู่ การกําหนดค่าจะยังคงอยู่ในบริการและสามารถเปิดใช้งานอีกครั้งได้ในภายหลัง

remove_metrics_config

pub async fn remove_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>

นำการกำหนดค่าเมตริกออกอย่างถาวร หากการกำหนดค่าใช้งานอยู่ บริการจะปิดใช้งานก่อน

remove_all_metrics_configs

pub async fn remove_all_metrics_configs(&self) -> TelemetryResult<String>

นำการกำหนดค่าเมตริกที่มีอยู่ทั้งหมดออก และปิดใช้งานการกำหนดค่าที่ใช้งานอยู่

get_active_metrics_config_uuids

pub async fn get_active_metrics_config_uuids(&self) -> TelemetryResult<Vec<String>>

ส่งคำค้นหาไปยังบริการเพื่อขอรายการ UUID สำหรับการกำหนดค่าทั้งหมดในสถานะ ที่ใช้งานอยู่

get_inactive_metrics_config_uuids

pub async fn get_inactive_metrics_config_uuids(&self) -> TelemetryResult<Vec<String>>

ค้นหาบริการเพื่อดูรายการ UUID สำหรับการกำหนดค่าทั้งหมดในสถานะไม่ได้ใช้งาน

การจัดการและการดึงข้อมูลรายงานเมตริก

ซึ่งช่วยให้คุณค้นหารายงานที่มีอยู่และเรียกข้อมูลรายงานที่รวบรวมได้

get_metrics_report

pub async fn get_metrics_report(&self, report_uuid: &str) -> TelemetryResult<MetricsReport>

เรียกข้อมูลรายงานเมตริกแบบเต็มสำหรับ UUID ของรายงานที่เฉพาะเจาะจง คุณสามารถรับ UUID ของรายงานจากการแจ้งเตือนได้โดยใช้ report_ready_callback หรือ โดยการเรียก get_ready_reports_info

get_ready_reports_info

pub async fn get_ready_reports_info(&self) -> TelemetryResult<Vec<ReportInfo>>

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

ประเภทหลัก การเรียกกลับ และการจัดการข้อผิดพลาด

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

การตอบกลับจาก API และประเภทข้อผิดพลาด

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

TelemetryResult

เมธอดส่วนใหญ่จะแสดงผล TelemetryResult<T> ซึ่งเป็นชื่อแทนสำหรับประเภท Result มาตรฐานที่ปรับให้เหมาะกับข้อผิดพลาดระดับบริการ

pub type TelemetryResult<T> = Result<T, TelemetryError>;

TelemetryError

TelemetryError struct จะห่อหุ้มความล้มเหลวทั้งหมดและให้ข้อมูลข้อผิดพลาดโดยละเอียดเฉพาะบริการ

TelemetryServiceStatusCodes

การแจงนับตัวเลขที่แสดงผลลัพธ์ของการเรียก API และสถานะบริการภายใน รหัสเหล่านี้ใช้ได้ทั้งใน TelemetryError และ TelemetryServiceStatus เช่น

ประเภทการเรียกกลับแบบอะซิงโครนัส

ผู้ฟังที่ลงทะเบียน (misc_status_callback และ report_ready_callback) ส่งประเภทเหล่านี้ไปยังไคลเอ็นต์เพื่อแจ้งข้อมูลอัปเดตเกี่ยวกับกระบวนการเบื้องหลัง

TelemetryServiceStatus

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

รายละเอียดสถานะ

การแจงนับนี้จะรวมบริบทข้อผิดพลาดที่เฉพาะเจาะจง หาก details ปรากฏใน TelemetryServiceStatus แสดงว่าเป็นตัวแปรใดตัวแปรหนึ่งต่อไปนี้

ตัวแปร Enum แต่ละตัวมีช่องเพิ่มเติมที่ให้บริบทมากยิ่งขึ้น

ReportInfo

ReportInfo struct ทำหน้าที่เป็นอาร์กิวเมนต์สำหรับreport_ready_callback closure ของ init ซึ่งลงทะเบียนไว้ในระหว่างการเริ่มต้นบริการ ซึ่งมีตัวระบุที่อธิบายรายงานเมตริกดังนี้

ฟิลด์ report_uuid เป็นฟิลด์เดียวที่จำเป็นสำหรับการดึงข้อมูลรายงานเมตริกเพิ่มเติม (ดู get_metrics_report) ส่วน config_uuid จะเป็นเพียงข้อมูลเพิ่มเติมเกี่ยวกับแหล่งที่มาของรายงาน