תוסף של Google Cloud Firestore

אתם צופים במסמכי התיעוד של Apigee Edge.
אפשר לעבור אל מסמכי התיעוד של Apigee X. מידע

גרסה: 2.0.2

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

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

יוצרים פרויקט Firebase במסוף Firebase שבו הנתונים מאוחסנים.
יוצרים מפתח לחשבון השירות.
משתמשים בתוכן של קובץ ה-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>

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

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

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

<?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 שנוצר מקובץ המפתח.	ללא.	כן.