Method: projects.locations.endpoints.queryData

שליחת שאילתות לרשת כדי לקבל מידע שמאוחסן בספר החשבונות, כמו חשבונות ועסקאות.

הגישה לשדות רגישים מסוימים, כמו יתרות בחשבון, עשויה להיות מוגבלת על סמך זהות השולח שנגזרת מהחתימה בבקשה. אם לשולח אין הרשאה, שדות רגישים יצונזרו מהתשובה וידווחו בשדה redactedFields.

בקשת HTTP


POST https://universalledger.googleapis.com/v1/{endpoint=projects/*/locations/*/endpoints/*}:queryData

כתובות ה-URL כתובות בתחביר של gRPC Transcoding.

פרמטרים של הנתיב

פרמטרים
endpoint

string

חובה. נקודת הקצה (endpoint) שממלאת את הבקשה. פורמט: projects/{project}/locations/{location}/endpoints/{endpoint} המיקום הוא אזור.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "serializedSignedQueryRequest": string
}
שדות
serializedSignedQueryRequest

string (bytes format)

חובה. ‫SignedQueryRequest שעבר סריאליזציה של protobuf כדי לשלוח שאילתה לרשת Universal Ledger.

מחרוזת בקידוד Base64.

גוף התשובה

הודעת תגובה ל-endpoints.queryData.

אם הפעולה מצליחה, גוף התשובה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "redactedFields": [
    {
      object (RedactedField)
    }
  ],

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "account": {
    object (Account)
  },
  "transactionState": {
    object (TransactionState)
  }
  // End of mutually exclusive fields.
}
שדות
redactedFields[]

object (RedactedField)

מציין אילו שדות צונזרו מהתגובה בגלל הגבלות הרשאה.
התוצאה הספציפית לשאילתה. ברשימה הבאה מופיעים שדות שמוציאים זה את זה. בתשובה יוגדר לכל היותר אחד מהשדות הבאים:
account

object (Account)

פרטי החשבון, אם השאילתה הייתה לגבי חשבון.
transactionState

object (TransactionState)

מצב העסקה, אם השאילתה הייתה לגבי עסקה.
סוף השדות שמוציאים זה את זה.

היקפי הרשאות

נדרש היקף ההרשאות הבא של OAuth:

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

ניתן למצוא מידע נוסף כאן: Authentication Overview.

הרשאות IAM

נדרשת הרשאת IAM הבאה במשאב endpoint:

  • universalledger.endpoints.readNetwork

מידע נוסף זמין במאמרי העזרה בנושא IAM.

TransactionState

הסטטוס של העסקה.

ייצוג ב-JSON 
{
  "transactionAttempts": [
    {
      object (TransactionAttempt)
    }
  ]
}
שדות
transactionAttempts[]

object (TransactionAttempt)

רשומה אחת לכל שליחה ידועה של העסקה למאמת שמטפל בבקשה.

RedactedField

מידע על שדה מצונזר בתשובה.

ייצוג ב-JSON 
{
  "redactedPath": string,
  "reason": string,
  "reasonCode": enum (Code)
}
שדות
redactedPath

string (FieldMask format)

פלט בלבד. נתיבי השדות המלאים שצונזרו מהמטען הייעודי (payload).

זוהי רשימה מופרדת בפסיקים של שמות שדות שמוגדרים במלואם. דוגמה: "user.displayName,photo"
reason

string

פלט בלבד. הסבר קריא לאנשים על הסיבה לצנזור השדות.
reasonCode

enum (Code)

פלט בלבד. קוד קריא למכונה שמסביר למה השדות צונזרו.

קוד

קודי השגיאה הקנוניים של ממשקי ה-API של gRPC.

לפעמים יכולים להיות כמה קודי שגיאה. השירותים צריכים להחזיר את קוד השגיאה הספציפי ביותר שרלוונטי. לדוגמה, אם שני הקודים רלוונטיים, עדיף להשתמש ב-OUT_OF_RANGE ולא ב-FAILED_PRECONDITION. באופן דומה, עדיף להשתמש ב-NOT_FOUND או ב-ALREADY_EXISTS במקום ב-FAILED_PRECONDITION.

טיפוסים בני מנייה (enum)
OK

לא שגיאה, מוחזרת כשהפעולה מצליחה.

מיפוי HTTP: ‏ ‎200 OK
CANCELLED

הפעולה בוטלה, בדרך כלל על ידי מבצע הקריאה.

מיפוי HTTP: ‏ 499 Client Closed Request
UNKNOWN

שגיאה לא ידועה. לדוגמה, השגיאה הזו יכולה להופיע כשערך Status שמתקבל ממרחב כתובות אחר שייך למרחב שגיאות שלא מוכר במרחב הכתובות הזה. גם שגיאות שנוצרות על ידי ממשקי API שלא מחזירים מספיק מידע על השגיאה עשויות להפוך לשגיאה הזו.

מיפוי HTTP: ‏500 שגיאת שרת פנימית
INVALID_ARGUMENT

הלקוח ציין ארגומנט לא תקין. חשוב לשים לב שהמאפיין הזה שונה מ-FAILED_PRECONDITION. הערך INVALID_ARGUMENT מציין ארגומנטים בעייתיים, בלי קשר למצב המערכת (למשל, שם קובץ בפורמט שגוי).

מיפוי HTTP: ‏ 400 Bad Request
DEADLINE_EXCEEDED

המועד האחרון חלף לפני שהפעולה הסתיימה. בפעולות שמשנות את מצב המערכת, יכול להיות שהשגיאה הזו תוחזר גם אם הפעולה הושלמה בהצלחה. לדוגמה, יכול להיות שתגובה מוצלחת מהשרת התעכבה מספיק זמן כדי שהמועד האחרון יחלוף.

מיפוי HTTP: ‏504 הזמן שהוקצב לשער חלף
NOT_FOUND

ישות מבוקשת כלשהי (למשל, קובץ או ספרייה) לא נמצאה.

הערה למפתחי שרתים: אם בקשה נדחית עבור קבוצה שלמה של משתמשים, למשל השקה הדרגתית של תכונה או רשימת היתרים לא מתועדת, אפשר להשתמש ב-NOT_FOUND. אם בקשה נדחית עבור משתמשים מסוימים בתוך קבוצת משתמשים, כמו בקרת גישה מבוססת-משתמש, צריך להשתמש ב-PERMISSION_DENIED.

מיפוי HTTP: ‏ שגיאת 404
ALREADY_EXISTS

הישות שהלקוח ניסה ליצור (למשל, קובץ או ספרייה) כבר קיימת.

מיפוי HTTP: ‏ 409 Conflict
PERMISSION_DENIED

למבצע הקריאה אין הרשאה לבצע את הפעולה שצוינה. אסור להשתמש ב-PERMISSION_DENIED לדחיות שנגרמו בגלל מיצוי של משאב כלשהו (במקום זאת, צריך להשתמש ב-RESOURCE_EXHAUSTED לשגיאות האלה). אסור להשתמש ב-PERMISSION_DENIED אם אי אפשר לזהות את מבצע הקריאה (במקום זאת, צריך להשתמש ב-UNAUTHENTICATED לשגיאות האלה). קוד השגיאה הזה לא מציין שהבקשה תקינה או שהישות המבוקשת קיימת או עומדת בתנאים מוקדמים אחרים.

מיפוי HTTP: ‏ 403 Forbidden
UNAUTHENTICATED

בבקשה אין פרטי כניסה תקפים לאימות הפעולה.

מיפוי HTTP: ‏ 401 Unauthorized
RESOURCE_EXHAUSTED

משאב כלשהו מוצה, אולי מכסה לכל משתמש, או אולי נגמר המקום במערכת הקבצים כולה.

מיפוי HTTP: ‏ 429 Too Many Requests
FAILED_PRECONDITION

הפעולה נדחתה כי המערכת לא במצב שנדרש לביצוע הפעולה. לדוגמה, הספרייה שרוצים למחוק לא ריקה, פעולת rmdir מופעלת על משהו שהוא לא ספרייה וכו'.

מפתחי שירותים יכולים להשתמש בהנחיות הבאות כדי להחליט בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE: (א) משתמשים ב-UNAVAILABLE אם הלקוח יכול לנסות שוב רק את הקריאה שנכשלה. ‫(ב) משתמשים ב-ABORTED אם הלקוח צריך לנסות שוב ברמה גבוהה יותר. לדוגמה, כשפעולת test-and-set שצוינה על ידי הלקוח נכשלת, זה מצביע על כך שהלקוח צריך להפעיל מחדש רצף של read-modify-write. (ג) משתמשים ב-FAILED_PRECONDITION אם הלקוח לא אמור לנסות שוב עד שמצב המערכת תוקן באופן מפורש. לדוגמה, אם הפעולה rmdir נכשלת כי הספרייה לא ריקה, צריך להחזיר את הערך FAILED_PRECONDITION כי הלקוח לא אמור לנסות שוב אלא אם הקבצים נמחקו מהספרייה.

מיפוי HTTP: ‏ 400 Bad Request
ABORTED

הפעולה בוטלה, בדרך כלל בגלל בעיה בו-זמנית כמו כשל בבדיקת רצף או ביטול עסקה.

בהנחיות שלמעלה מוסבר איך לבחור בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE.

מיפוי HTTP: ‏ 409 Conflict
OUT_OF_RANGE

הפעולה בוצעה מחוץ לטווח התקין. למשל, חיפוש או קריאה מעבר לסוף הקובץ.

בניגוד ל-INVALID_ARGUMENT, השגיאה הזו מצביעה על בעיה שאפשר לפתור אם מצב המערכת משתנה. לדוגמה, מערכת קבצים של 32 ביט תיצור את INVALID_ARGUMENT אם תתבקש לקרוא בהיסט שלא נמצא בטווח [0,2^32-1], אבל היא תיצור את OUT_OF_RANGE אם תתבקש לקרוא מהיסט שעובר את גודל הקובץ הנוכחי.

יש חפיפה מסוימת בין FAILED_PRECONDITION לבין OUT_OF_RANGE. מומלץ להשתמש ב-OUT_OF_RANGE (השגיאה הספציפית יותר) כשהיא רלוונטית, כדי שגורמים שמתקשרים שעוברים על מרחב יוכלו לחפש בקלות שגיאת OUT_OF_RANGE כדי לזהות מתי הם סיימו.

מיפוי HTTP: ‏ 400 Bad Request
UNIMPLEMENTED

הפעולה לא הוטמעה או לא נתמכת/מופעלת בשירות הזה.

מיפוי HTTP: ‏ 501 Not Implemented
INTERNAL

שגיאות פנימיות. המשמעות היא שחלק מהקבועים שהמערכת הבסיסית מצפה להם הופרו. קוד השגיאה הזה שמור לשגיאות חמורות.

מיפוי HTTP: ‏500 שגיאת שרת פנימית
UNAVAILABLE

השירות הזה לא זמין כרגע. סביר להניח שמדובר במצב זמני, שאפשר לתקן על ידי ניסיון חוזר עם השהיה. חשוב לזכור שלא תמיד בטוח לנסות שוב פעולות שהן לא אידמפוטנטיות.

בהנחיות שלמעלה מוסבר איך לבחור בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE.

מיפוי HTTP: ‏503 Service Unavailable
DATA_LOSS

אובדן נתונים או פגיעה בנתונים שלא ניתן לשחזר.

מיפוי HTTP: ‏500 שגיאת שרת פנימית