תוסף של Google Cloud Firestore

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

גרסה: 1.4.1

יצירה, קריאה או מחיקה של נתונים במסד הנתונים של Cloud Firestore.

התוכן הזה מספק הפניה להגדרה של התוסף הזה ולשימוש בו. לפני השימוש בתוסף הזה דרך שרת proxy של API, צריך:

  1. יוצרים פרויקט Firebase במסוף Firebase שבו מאוחסנים הנתונים.

  2. יוצרים מפתח לחשבון השירות.

  3. יש להשתמש בתוכן של קובץ ה-JSON שמכיל את המפתח שהתקבל במהלך הוספה והגדרה של התוסף באמצעות ההפניה לתצורה.

מידע על Cloud Firestore

הנתונים של Cloud Firestore מאוחסנים במסמכים שמאוחסנים באוספים. מערכת Cloud Firestore יוצרת אוספים ומסמכים באופן מפורש, בפעם הראשונה שמוסיפים נתונים למסמך. אין צורך ליצור אוספים או מסמכים באופן מפורש.

מידע נוסף על Cloud Firestore באופן כללי זמין במאמר תחילת העבודה עם Firestore בתיעוד של Cloud Firestore.

טעימות

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

הוספת נתונים

המדיניות הבאה של תוספי יתרונות מרכזיים מוסיפה מסמך בשם freewill@example.com לאוסף users. המאפיין data מציין את השדות והערכים של המסמך החדש.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Add-User-Data">
    <DisplayName>Add User Data</DisplayName>
    <Connector>my-cloud-firestore-extension</Connector>
    <Action>setDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "freewill@example.com",
        "data" : {
            "firstName": "Will",
            "lastName": "Witman",
            "address": "270-8243 Tempor St.",
            "city": "Fort Worth",
            "region": "TX",
            "postalCode": "86519",
            "email": "freewill@example.com",
            "username": "freewill444"
        }
    }]]></Input>
</ConnectorCallout>

הצגת נתונים

בדוגמה הזו, המדיניות של תוסף היתרונות המרכזיים מאחזרת את הערך של המסמך freewill@example.com מהאוסף users. כאן, המאפיין parsed של הרכיב <Output> מוגדר ל-false, כך שהתוצאה שתוחזר תהיה JSON כמחרוזת, ולא JSON שנותח לאובייקט. למידע נוסף, עיינו בחומר העזר בנושא <Output>.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Get-User-Data">
    <DisplayName>Get User Data</DisplayName>
    <Connector>straut-cloud-firestore-extension</Connector>
    <Action>getDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "freewill@example.com"
    }]]></Input>
    <Output parsed="false">firestore.userdata.retrieved</Output>
</ConnectorCallout>

במדיניות הבאה בנושא הקצאת הודעה, נעשה שימוש בערך של המשתנה שמאחסן את התגובה של התוסף כדי להקצות את המטען הייעודי (payload) של התגובה.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage name="CopyUserDataToResponse">
    <DisplayName>Copy User Data To Response</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{firestore.userdata.retrieved}</Payload>
    </Set>
</AssignMessage>

מחיקת נתונים

בדוגמה הזו, המדיניות של נכס היתרונות המרכזיים של תוספים מוחקת את המסמך lizzie@example.com מהאוסף users.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Delete-User-Data">
    <DisplayName>Delete User Data</DisplayName>
    <Connector>my-cloud-firestore-extension</Connector>
    <Action>deleteDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "lizzie@example.com"
    }]]></Input>
</ConnectorCallout>

נתוני השאילתה

בדוגמה הזו, המדיניות בנושא תוספי יתרונות מרכזיים מפעילה שאילתות על אוסף cities. תוצאות השאילתה מסוננות לפי השדות state ו-population. כאן, המאפיין parsed של הרכיב <Output> מוגדר ל-false, כך שהתוצאה שתוחזר תהיה JSON כמחרוזת, ולא JSON שנותח לאובייקט. למידע נוסף, עיינו בחומר העזר בנושא <Output>.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Query-City-Data">
    <DisplayName>Query City Data</DisplayName>
    <Connector>cloud-firestore-extension</Connector>
    <Action>query</Action>
    <Input><![CDATA[{
        "colName":"cities",
        "queryArray":[
          ["state", "==", "CA"],
          ["population","<",1000000]
        ]
    }]]></Input>
    <Output parsed="false">compound-query-output</Output>
</ConnectorCallout>

במדיניות הבאה בנושא הקצאת הודעה, נעשה שימוש בערך של המשתנה שמאחסן את התגובה של התוסף כדי להקצות את המטען הייעודי (payload) של התגובה.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage name="CopyQueryResultsToResponse">
    <DisplayName>Copy Query Results To Response</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{firestore.querydata.retrieved}</Payload>
    </Set>
</AssignMessage>

פעולות

deleteDocument

מחיקת מסמך יחיד מאוסף.

פרמטרים של בקשה

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>
פרמטר התיאור תיאור ברירת המחדל נדרש
colName שם האוסף שמכיל את המסמך למחיקה. מחרוזת ללא. כן.
docName שם המסמך למחיקה. מחרוזת ללא. כן.

תשובה

ללא.

getDocument

מאחזר את התוכן של מסמך יחיד.

פרמטרים של בקשה

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>
פרמטר התיאור תיאור ברירת המחדל נדרש
colName שם האוסף שממנו יש לאחזר את המסמך. מחרוזת ללא. כן.
docName שם המסמך שיש לאחזר. מחרוזת ללא. כן.

תשובה

אובייקט שמכיל את תוכן המסמך בפורמט JSON.

שאילתה

שולח שאילתה על אוסף לפי התנאים המציינים שיוצרים מסנן.

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

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

  • רכיב שמאלי שמציין את שדה האוסף.
  • רכיב אמצעי שמציין את האופרטור.
  • רכיב ימני שמציין את הערך של שדה האוסף.

בדוגמה הבאה מציינים שני מערכי תנאים לסינון על סמך השדות state ו-population של האוסף:

<Input><![CDATA[{
  "colName":"cities",
  "queryArray":[
    ["state", "==", "CA"],
    ["population","<",1000000]
  ]
}]]></Input>

בזמן ריצה, פעולה זו מפורשת כשאילתה כמו בדוגמה הבאה:

יש לבחור את כל הערים שבהן מדינה = 'CA' ואוכלוסייה < 1000000

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

פרמטרים של בקשה

תחביר

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "queryArray" : "queryArray": query-condition-array
}]]></Input>

דוגמה

בדוגמה הזו, הפרמטר queryArray מציין שני תנאים שבהם יש לסנן את האוסף cities שצוין בפרמטר colName.

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

<Input><![CDATA[{
  "colName":"cities",
  "queryArray":[["state", "==", "CA"],["population","<",1000000]]
}]]></Input>

בזמן ריצה, פעולה זו מפורשת כשאילתה כמו בדוגמה הבאה:

יש לבחור את כל הערים שבהן מדינה = 'CA' ואוכלוסייה < 1000000

פרמטר התיאור תיאור ברירת המחדל נדרש
colName שם האוסף שאליו יש לשלוח שאילתה. מחרוזת ללא. כן.
queryArray מערך של מערכי תנאים, שיחד, מציינים את חלקי המסנן. צריך לציין מערך ריק כדי להשמיט תנאים (ולא סינון תוצאות). Array ללא. כן.

תשובה

אובייקט שמכיל את תוכן המסמך בפורמט JSON.

setDocument

העתקת מסמך לאוסף של Cloud Firestore. אם המסמך כבר קיים באוסף, הוא יחליף אותו.

פרמטרים של בקשה

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name",
  "data" : "data-to-copy"
}]]></Input>
פרמטר התיאור תיאור ברירת המחדל נדרש
colName שם האוסף שבו יש ליצור את המסמך. מחרוזת ללא. כן.
docName שם המסמך שאליו יש להעתיק את data. מחרוזת ללא. כן.
נתונים נתונים להעתקה אל docName. הוא חייב להיות אובייקט JSON חוקי. אין תמיכה במערכים. אובייקט ללא. לא.

תשובה

ללא.

סימוכין לתצורה

במהלך ההגדרה והפריסה של התוסף הזה לשימוש בשרתי proxy של API, צריך להשתמש בהגדרות הבאות. לשלבים להגדרת תוסף באמצעות מסוף Apigee, אפשר לעיין במאמר הוספה והגדרה של תוסף.

מאפיינים נפוצים של תוספים

המאפיינים הבאים קיימים בכל תוסף.

נכס תיאור ברירת המחדל נדרש
name השם שבחרת לתצורה הזו של התוסף. ללא כן
packageName השם של חבילת התוסף כפי שהוא סופק על ידי Apigee Edge. ללא כן
version מספר הגרסה של חבילת התוסף שממנה מגדירים את התוסף. ללא כן
configuration ערך הגדרה ספציפי לתוסף שרוצים להוסיף. מאפיינים לחבילת תוספים זו ללא כן

המאפיינים של חבילת התוספים הזו

נכס התיאור ברירת המחדל נדרש
firestoreDB כתובת URL למסד הנתונים של Cloud Firestore שבה התוסף הזה צריך להשתמש לצורך שליחת בקשות. כתובת ה-URL הזו מופיעה בדרך כלל בתבנית https://DATABASE_NAME.firebaseio.com. ללא. כן.
פרטי כניסה זה התוכן של קובץ המפתח שיצרת באמצעות ההוראות של Firebase, כשמזינים אותו במסוף Apigee Edge. כשהערך הזה נשלח דרך ממשק ה-API לניהול, הוא ערך בקידוד base64 שנוצר מקובץ המפתח. ללא. כן.