origami מדריך לשימוש בשדה API במערכת Origami.ms

rabin · ביום ראשון בשעה 09:57

בס"ד

מדריך לשימוש בשדה API במערכת Origami.ms

מבוא:

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

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

הנתונים המתקבלים מופיעים בהתאם להגדרות שהוגדרו מראש, ומוצגים ברשימה לבחירה (Drop-Down), כך שהמשתמש יכול לבחור את הערך המתאים מבין האפשרויות.

שלב 1: הגדרות בסיסיות של השדה

שם השדה (field_name): יש להזין שם לשדה כפי שיופיע במערכת, למשל: "כתובת חיפוש".
תיאור השדה (tooltip_description): תיאור קצר המסביר את מטרת השדה והשימוש בו, לדוגמה: "שדה לחיפוש כתובת לפי נתוני OpenStreetMap".

שלב 2: הגדרות API

API קישור (api_url): הכניסו את כתובת ה-URL של ה-API אליו יבוצע החיפוש. לדוגמה:
HTTP:
```
https://nominatim.openstreetmap.org/search?format=json
```
סוג פעולה (action_type): בחרו את סוג הבקשה (GET או POST). בדוגמה שלנו נשתמש ב-GET.

שלב 3: מיפוי פרמטרים בנתוני החיפוש

id מזהה המאפיין (id_prop_name): כאן יש להזין את שם הפרמטר של המזהה (ID) במערך התשובה, חייב להיות מזהה חד ערכי. בדוגמה, הפרמטר הוא place_id.
text שם המאפיין (text_prop_name): הפרמטר שיוצג למשתמש כתוצאה מחיפוש. בדוגמה זו, זהו display_name, אשר מכיל את הכתובת המלאה כמו "ירושלים, בני ברק, ישראל".
שם מאפיין לחיפוש (search_prop_name): השם של פרמטר החיפוש שנשלח ל-API. בדוגמה זו, נשתמש בפרמטר q עבור החיפוש.
שם מאפיין לעמוד (page_prop_name): ערך מוגדר כברירת מחדל ואינו ניתן לשינוי. כאן לדוגמה, נשתמש בפרמטר page.
מאפיינים נוספים (custom_validation[extra_props]): קלט טקסט המאפשר הגדרת פרמטרים נוספים, לא פעיל כרגע.
פילטר (custom_validation[filters]): הפילטרים בשדה מאפשרים לכם לבחור שדות API אחרים, ושולח את שמות השדות שהוגדרו + הערך id שלהם (ללא הטקסט).

שלב 4: הגדרות נוספות לשדה

מספר תווים מינימלי לחיפוש (min_search_length): מגדיר את מספר התווים המינימלי שעל המשתמש להקיש לפני שהחיפוש יופעל. בדוגמה זו, נזין 3.
מספר תוצאות (results_per_page): קובע את מספר התוצאות שיוצגו באוריגמי בכל חיפוש של תוצאות. בדוגמה, נבחר להציג 50 תוצאות.
זמן תגובה מקסימלי (response_timeout_seconds): מגביל את הזמן שהמערכת תחכה לתשובת ה-API לפני שתציג הודעת שגיאה. בדוגמה, נזין 3 שניות.

דוגמה לקריאת API עם ערכים לדוגמה

נניח שהמשתמש מקיש את השאילתה "ירושלים בני ברק" בשדה החיפוש. הקריאה שתישלח ל-API תיראה כך:

HTTP:

https://nominatim.openstreetmap.org/search?format=json&q=ירושלים בניברק&instance_id=658e841ad55b828d150e1724&field_data_name=fld_1872&filter=&page=1

מה נשלח בבקשה

q – מייצג את הערך שחיפש המשתמש.
instance_id – מזהה המופע באוריגמי, מזהה ייחודי לשדה במערכת.
field_data_name – שם השדה באוריגמי, במקרה הזה fld_1872.
page – מספר העמוד.
filter – ניתן להגדיר בפילטר שדות api אחרים בישות יישלח, ויישלחו שמות השדות שהוגדרו לפילטר, יחד עם מזהי ה-ID שלהם בלבד, ללא הטקסט. אם לא הוגדר פילטר, ישלח הערך כ-"ריק". לדוגמא: filter[fld_1224]: 38.

חשוב לדעת:

אוריגמי תמיד שולחת את הפרמטרים instance_id ,field_data_name, filter, ו-page, מה שעלול ליצור בעיות עם מערכות שלא מקבלות פרמטרים נוספים בכתובת ה-API.
בכל הזנה של ערך בשדה נשלחת קריאה חדשה לשרת.

דוגמה לתשובת ה-API

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

JSON:

[

    {

        "place_id": 194257751,

        "display_name": "ירושלים, הר שלום, בני ברק, נפת תל אביב, מחוז תל אביב, ישראל",

        "lat": "32.08502095",

        "lon": "34.8298572"

    },

    {

        "place_id": 194311477,

        "display_name": "ירושלים, הר שלום, בני ברק, נפת תל אביב, מחוז תל אביב, ישראל",

        "lat": "32.0874445",

        "lon": "34.830255"

    }

]

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

מה אוריגמי שומרת מהתשובה

id: הערך של place_id יישמר כערך ה-ID שהוגדר בשדה.
text: הערך של display_name יישמר יישמר כערך הטקסט להצגה שהוגדר בשדה.

במקרה זה, אוריגמי תשמור את הכתובת המלאה, לדוגמה: "ירושלים, הר שלום, בני ברק, נפת תל אביב, מחוז תל אביב, ישראל". ואת המזהה "194257751".

JSON:

"fld_1872": { "id": 194257751, "text": "בני ברק, נפת תל אביב, מחוז תל אביב, ישראל" }

סיכום

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

rabin · ביום ראשון בשעה 18:46

למתחילים @David Hadas כתב את זה בצורה יותר מפורטת.

שדה API באוריגמי

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

docs.google.com