Package google.longrunning

ดัชนี

การทำงาน

จัดการการดำเนินการที่ใช้เวลานานด้วยบริการ API

เมื่อเมธอด API ใช้เวลานานในการทำงาน เมธอดสามารถออกแบบให้ส่งกลับ Operation ไปยังไคลเอ็นต์ได้ และไคลเอ็นต์จะใช้อินเทอร์เฟซนี้เพื่อรับการตอบสนองจริงแบบไม่พร้อมกันโดยการสำรวจทรัพยากรการดำเนินการ หรือส่งผ่านทรัพยากรการดำเนินการไปยัง API อื่น (เช่น Pub/Sub API) เพื่อรับการตอบกลับ บริการ API ที่ส่งกลับการดำเนินการที่ใช้เวลานานควรใช้งานอินเทอร์เฟซ Operations เพื่อให้นักพัฒนาซอฟต์แวร์ได้รับประสบการณ์การใช้งานไคลเอ็นต์ที่สอดคล้องกัน

CancelOperation

rpc CancelOperation(CancelOperationRequest) returns (Empty)

เริ่มการยกเลิกแบบไม่พร้อมกันในการดำเนินงานที่ใช้เวลานาน เซิร์ฟเวอร์พยายามอย่างดีที่สุดที่จะยกเลิกการดำเนินการ แต่ไม่สามารถรับประกันความสำเร็จได้ หากเซิร์ฟเวอร์ไม่รองรับวิธีการนี้ ระบบจะแสดงผล google.rpc.Code.UNIMPLEMENTED ลูกค้าสามารถใช้ Operations.GetOperation หรือวิธีการอื่นๆ เพื่อตรวจสอบว่าการยกเลิกสำเร็จหรือไม่ หรือว่าการดำเนินการเสร็จสมบูรณ์แล้วแม้จะยกเลิกไปแล้วหรือไม่ เมื่อยกเลิกสำเร็จ การดำเนินการจะไม่ถูกลบ แต่จะกลายเป็นการดำเนินการที่มีค่า Operation.error ที่มีค่า google.rpc.Status.code เท่ากับ 1 ซึ่งสอดคล้องกับ Code.CANCELLED

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth ต่อไปนี้

  • https://www.googleapis.com/auth/cloud-platform
DeleteOperation

rpc DeleteOperation(DeleteOperationRequest) returns (Empty)

ลบการดำเนินการที่ใช้เวลานาน วิธีการนี้บ่งบอกว่าลูกค้าไม่สนใจผลการดำเนินการอีกต่อไป ไม่ใช่ยกเลิกการดำเนินการ หากเซิร์ฟเวอร์ไม่รองรับวิธีการนี้ ระบบจะแสดงผล google.rpc.Code.UNIMPLEMENTED

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth ต่อไปนี้

  • https://www.googleapis.com/auth/cloud-platform
GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

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

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth ต่อไปนี้

  • https://www.googleapis.com/auth/cloud-platform
ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

แสดงรายการการดำเนินการที่ตรงกับตัวกรองที่ระบุในคำขอ หากเซิร์ฟเวอร์ไม่รองรับวิธีการนี้ ระบบจะแสดงผล UNIMPLEMENTED

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth ต่อไปนี้

  • https://www.googleapis.com/auth/cloud-platform
WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation)

รอจนกระทั่งการดำเนินการที่ใช้เวลานานที่ระบุเสร็จสิ้น หรือถึงระยะหมดเวลาที่ระบุไว้ไม่เกินกำหนด แล้วกลับสู่สถานะล่าสุด หากดำเนินการเสร็จแล้ว ระบบจะแสดงผลสถานะล่าสุดทันที หากการหมดเวลาที่ระบุมากกว่าระยะหมดเวลา HTTP/RPC เริ่มต้น ระบบจะใช้ระยะหมดเวลาของ HTTP/RPC หากเซิร์ฟเวอร์ไม่รองรับเมธอดนี้ ระบบจะแสดง google.rpc.Code.UNIMPLEMENTED โปรดทราบว่าวิธีนี้เป็นวิธีที่ดีที่สุด โดยฟังก์ชันอาจคืนค่าสถานะล่าสุดก่อนหมดเวลาที่ระบุไว้ (รวมถึงทันที) ซึ่งหมายความว่าแม้แต่การตอบสนองในทันทีก็ไม่ได้เป็นการรับประกันว่าการดำเนินการจะเสร็จสิ้น

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth ต่อไปนี้

  • https://www.googleapis.com/auth/cloud-platform

CancelOperationRequest

ข้อความคำขอสำหรับ Operations.CancelOperation

ช่อง
name

string

ชื่อของทรัพยากรการดำเนินการที่จะยกเลิก

DeleteOperationRequest

ข้อความคำขอสำหรับ Operations.DeleteOperation

ช่อง
name

string

ชื่อของทรัพยากรการดำเนินการที่จะลบ

GetOperationRequest

ข้อความคำขอสำหรับ Operations.GetOperation

ช่อง
name

string

ชื่อของทรัพยากรการดำเนินการ

ListOperationsRequest

ข้อความคำขอสำหรับ Operations.ListOperations

ช่อง
name

string

ชื่อทรัพยากรหลักของการดำเนินการ
filter

string

ตัวกรองรายการมาตรฐาน
page_size

int32

ขนาดหน้ารายการมาตรฐาน
page_token

string

โทเค็นหน้ารายการมาตรฐาน

ListOperationsResponse

ข้อความตอบกลับสำหรับ Operations.ListOperations

ช่อง
operations[]

Operation

รายการการดำเนินการที่ตรงกับตัวกรองที่ระบุในคำขอ
next_page_token

string

โทเค็นหน้าถัดไปของรายการมาตรฐาน

การดำเนินการ

ทรัพยากรนี้แสดงการดำเนินการที่ใช้เวลานานซึ่งเป็นผลจากการเรียก API ของเครือข่าย

ช่อง
name

string

ชื่อที่เซิร์ฟเวอร์กำหนด ซึ่งจะไม่ซ้ำกันภายในบริการเดียวกันที่ส่งคืนชื่อในตอนแรก หากคุณใช้การแมป HTTP เริ่มต้น name ควรเป็นชื่อทรัพยากรที่ลงท้ายด้วย operations/{unique_id}
metadata

Any

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

bool

หากค่าเป็น false หมายความว่าการดำเนินการยังอยู่ระหว่างดำเนินการ หากเป็น true แสดงว่าการดำเนินการเสร็จสิ้นแล้ว และมี error หรือ response พร้อมใช้งาน
ฟิลด์สหภาพ result ผลการดำเนินการ ซึ่งอาจเป็น error หรือ response ที่ถูกต้องก็ได้ หาก done == false ไม่ได้ตั้งค่าทั้ง error และ response หาก done == true จะตั้งค่า error หรือ response ได้อย่างใดอย่างหนึ่งเท่านั้น บริการบางอย่างอาจไม่ได้แสดงผลลัพธ์ result ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
error

Status

ผลข้อผิดพลาดของการดำเนินการในกรณีที่ดำเนินการไม่สำเร็จหรือการยกเลิก
response

Any

การตอบสนองปกติที่ประสบความสำเร็จของการดำเนินการ หากเมธอดเดิมไม่แสดงผลข้อมูลเกี่ยวกับความสำเร็จ เช่น Delete การตอบกลับจะเป็น google.protobuf.Empty หากวิธีการเดิมเป็นมาตรฐาน Get/Create/Update คำตอบควรเป็นแหล่งข้อมูล สำหรับวิธีการอื่นๆ การตอบกลับควรมีประเภท XxxResponse โดยที่ Xxx เป็นชื่อเมธอดดั้งเดิม ตัวอย่างเช่น หากชื่อเมธอดเดิมคือ TakeSnapshot() ประเภทการตอบกลับที่สรุปได้จะเป็น TakeSnapshotResponse

WaitOperationRequest

ข้อความคำขอสำหรับ Operations.WaitOperation

ช่อง
name

string

ชื่อของทรัพยากรการดำเนินการที่จะรอ
timeout

Duration

ระยะเวลาสูงสุดที่จะรอก่อนหมดเวลา หากเว้นว่างไว้ ค่ารอจะเป็นเวลามากที่สุดตามเวลาที่โปรโตคอล HTTP/RPC ที่เกี่ยวข้องอนุญาต หากมีการระบุกำหนดเวลาของบริบท RPC ไว้ ระบบจะใช้กำหนดเวลาที่สั้นกว่า