תוסף של 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 באמצעות מדיניות ExtensionCallout.

הוספת נתונים

המדיניות ExtensionCallout הבאה מוסיפה מסמך בשם 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>

קבלת נתונים

בדוגמה הזו, המדיניות ExtensionCallout מאחזרת את הערך של המסמך 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>

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

<?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>

מחיקת נתונים

בדוגמה הזו, מדיניות ExtensionCallout מוחקת את המסמך 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>

שאילתות על נתונים

בדוגמה הזו, המדיניות ExtensionCallout שולחת שאילתה לאוסף 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>

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

<?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>

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

בוחרים את כל הערים שבהן state = 'CA' ו-population < 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>

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

בוחרים את כל הערים שבהן state = 'CA' ו-population < 1000000

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

תשובה

אובייקט שמכיל את תוכן המסמך בפורמט 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. ללא. כן.
פרטי כניסה כשמזינים את התוכן הזה במסוף Apigee Edge, זה התוכן של קובץ המפתח שיצרתם באמצעות ההוראות של Firebase. כששולחים אותו דרך Management API, זהו ערך בקידוד Base64 שנוצר מקובץ המפתח. ללא. כן.