streamalism.org

1. הקדמה

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

2. מה זה OData?

OData הוא תקן OASIS ו- ISO / IEC לגישה לנתונים באמצעות ממשק API RESTful. ככזה, הוא מאפשר לצרכן לגלות ולנווט בערכות נתונים באמצעות שיחות HTTP רגילות.

למשל, אנו יכולים לגשת לאחד משירותי ה- OData הזמינים לציבור באמצעות פשוט סִלְסוּל תוחם אחד:

תלתל-s //services.odata.org/V2/Northwind/Northwind.svc/ אזורים אזורים //services.odata.org/V2/Northwind/Northwind.svc/ אזורים ... שאר תגובת ה- XML ​​הושמעה

נכון לכתיבת שורות אלה, פרוטוקול OData נמצא בגרסתו הרביעית - 4.01 ליתר דיוק. OData V4 הגיע לרמת התקן OASIS בשנת 2014, אך יש לו היסטוריה ארוכה יותר. אנו יכולים להתחקות אחר שורשיו לפרויקט של מיקרוסופט בשם Astoria, ששמו שונה ל- ADO.Net Data Services בשנת 2007. רשומת הבלוג המקורית שהודיעה על פרויקט זה עדיין זמינה בבלוג OData של מיקרוסופט.

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

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

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

3. מושגי OData

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

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

המפרט מחייב כי מסמך מטא-נתונים זה חייב להיות זמין במיקום הסטנדרטי מטא נתונים $ בכתובת ה- URL הבסיסית המשמשת לגישה לשירות. למשל, אם יש לנו שירות OData זמין בכתובת //example.org/odata.svc/, ואז מסמך המטא-נתונים שלו יהיה זמין בכתובת //example.org/odata.svc/$metadata.

המסמך שהוחזר מכיל חבורה של XML המתארת ​​את הסכימות הנתמכות על ידי שרת זה:

   ... אלמנטים של סכמה הושמטו 

בואו נפרק את המסמך הזה לחלקים העיקריים שלו.

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

א שירותי נתונים לאלמנט יכול להיות אחד או יותר סכֵימָה אלמנטים, כל אחד מהם מתאר מערך נתונים זמין. מאז תיאור מלא של האלמנטים הזמינים בא סכֵימָה מעבר לתחום מאמר זה, אנו נתמקד בחשובים החשובים ביותר: EntityTypes, Associations, ו EntitySets.

3.1. EntityType אֵלֵמֶנט

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

הנה, שלנו CarMaker יש רק שני מאפיינים - תְעוּדַת זֶהוּת ו שֵׁם - ועמותה לאחרת EntityType. ה מקש sאלמנט ub מגדיר את המפתח העיקרי של הישות להיות שלה תְעוּדַת זֶהוּת רכוש, וכל אחד מהם תכונה רכיב מכיל נתונים על מאפיין של ישות כגון שמו, סוגו או בטלותו.

א ניווט נכס הוא נכס מסוג מיוחד המתאר "נקודת גישה" לישות קשורה.

3.2. אִרגוּן אֵלֵמֶנט

An אִרגוּן אלמנט מתאר קשר בין שתי ישויות, הכולל את הריבוי בכל קצה ואופציה מגבלת שלמות התייחסותית:

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

3.3. EntitySet אֵלֵמֶנט

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

ה EntityContainer אלמנט, שהוא אלמנט סכימה ברמה העליונה, מקבץ את כל הזמינים EntitySets:

בדוגמה הפשוטה שלנו, יש לנו רק שניים EntitySets, אבל אנחנו יכולים גם להוסיף תצוגות נוספות, כגון ForeignCarMakers אוֹ HistoricCarMakers.

4. כתובות אתרים ושיטות OData

על מנת לגשת לנתונים שנחשפו על ידי שירות OData, אנו משתמשים בפעלים HTTP הרגילים:

• GET מחזיר ישות אחת או יותר
• POST מוסיף ישות חדשה לקיים סט ישויות
• PUT מחליף ישות נתונה
• PATCH מחליף מאפיינים ספציפיים של ישות נתונה
• DELETE מסיר ישות נתונה

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

בואו נסתכל על כתובת אתר לדוגמא ששימשה לגישה לשירות OData הקודם שלנו:

//example.org/odata/CarMakers 

החלק הראשון של כתובת אתר זו, החל מהפרוטוקול עד ל- odata / קטע שביל, מכונה כתובת שורש שירות והוא זהה לכל נתיבי המשאבים של שירות זה. מכיוון ששורש השירות הוא תמיד זהה, נחליף אותו בדגימות ה- URL הבאות באליפסה (“...”).

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

  // localhost: 8080 / odata / CarMakers CarMakers 2019-04-06T17: 51: 33.588-03: 00 // localhost: 8080 / odata / CarMakers (1L) CarMakers 2019-04-06T17: 51: 33.589-03: 00 1 מנועים מיוחדים ... ערכים אחרים הושמטו 

המסמך שהוחזר מכיל כְּנִיסָה אלמנט לכל אחד CarMaker למשל.

בואו נסתכל מקרוב על איזה מידע יש לנו:

• תְעוּדַת זֶהוּת: קישור לישות ספציפית זו
• כותרת / מחבר / מעודכן: מטא נתונים על ערך זה
• קישור רכיבים: קישורים המשמשים להצביע על משאב המשמש לעריכת הישות (rel = ”ערוך”) או לגופים קשורים. במקרה זה, יש לנו קישור שלוקח אותנו לסט של דגם של מכונית ישויות הקשורות בפרט זה CarMaker.
• תוֹכֶן: ערכי נכסים של דגם של מכונית יֵשׁוּת

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

5. אפשרויות שאילתה

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

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

5.1. הדף העליון ו דלג על $

אנחנו יכולים לנווט במערך נתונים גדול באמצעות הדף העליון an דלג על $ אפשרויות שאילתה:

... / CarMakers? $ Top = 10 & $ skip = 10 

הדף העליון אומר לשירות שאנחנו רוצים רק את 10 הרשומות הראשונות של מייצרי מכוניות מערך ישויות. א דלג על $, אשר מוחל לפני $ למעלה, אומר לשרת לדלג על 10 הרשומות הראשונות.

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

... / CarMakers / $ count 

משאב זה מייצר א טקסט / רגיל מסמך המכיל את גודל הערכה המתאימה. כאן עלינו לשים לב לגרסת ה- OData הספציפית הנתמכת על ידי ספק. בעוד OData V2 תומך ספירת $ כמשאב משנה מאוסף, V4 מאפשר להשתמש בו כפרמטר שאילתה. במקרה הזה, ספירת $ הוא בוליאני, לכן עלינו לשנות את כתובת האתר בהתאם:

... / CarMakers? $ Count = true 

5.2. מסנן $

אנו משתמשים ב- מסנן $ אפשרות שאילתה ל להגביל את הישויות שהוחזרו מנתון סט ישויות לאלו התואמים את הקריטריונים הנתונים. הערך עבור מסנן $ הוא ביטוי הגיוני התומך במפעילים בסיסיים, קיבוץ ומספר פונקציות שימושיות. לדוגמא, בואו לבנות שאילתה שמחזירה הכל CarMaker מקרים שבהם שֵׁם המאפיין מתחיל באות 'B':

... / CarMakers? $ Filter = startswith (שם, 'B') 

עכשיו, בואו נשלב כמה אופרטורים לוגיים לחיפוש CarModels של מסוים שָׁנָה ו יַצרָן:

... / CarModels? $ Filter = שנה שווה שנת 2008 ו- CarMakerDetails / שם שווה 'BWM' 

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

5.3. $ להרחיב

כברירת מחדל, שאילתת OData אינה מחזירה נתונים לגופים קשורים, וזה בדרך כלל בסדר. אנחנו יכולים להשתמש ב- $ להרחיב אפשרות שאילתה לבקש שהנתונים של ישות קשורה נתונה ייכללו בתוכן הראשי.

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

... / CarModels (1L)? $ Expand = CarMakerDetails 

המסמך שהוחזר כולל כעת את CarMaker נתונים כחלק מהישות הקשורה:

  //example.org/odata/CarModels(1L) CarModels 2019-04-07T11: 33: 38.467-03: 00 //example.org/odata/CarMakers(1L) CarMakers 2019-04-07T11: 33: 38.492-03 : 00 1 מנועים מיוחדים 1 1 Muze SM001 2018 

5.4. בחר $

אנו משתמשים באפשרות השאילתה $ select כדי להודיע ​​לשירות OData כי עליו להחזיר רק את הערכים עבור המאפיינים הנתונים. זה שימושי בתרחישים שבהם לגופים שלנו יש מספר רב של נכסים, אך אנו מעוניינים רק בחלק מהם.

בואו נשתמש באפשרות זו בשאילתה שמחזירה רק את שֵׁם ו מק"ט נכסים:

... / CarModels (1L)? $ Select = שם, מק"ט 

למסמך שנוצר כעת יש רק את המאפיינים המבוקשים:

... xml הושמט Muze SM001 ... xml הושמט

אנו יכולים גם לראות כי אפילו ישויות קשורות הושמטו. כדי לכלול אותם, נצטרך לכלול את שם הקשר ב- בחר $ אוֹפְּצִיָה.

5.5. $ orderBy

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

... / CarModels? $ OrderBy = שם asc, Sku desc 

שאילתה זו תביא לרשימה של CarModels מסודרים לפי שמם ומק"ט, בכיוונים עולים ויורדים בהתאמה.

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

5.6. פורמט $

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

לדוגמה, אנחנו יכולים להשתמש ג'סון כקיצור של יישום / json:

... / CarModels? $ Format = json 

כתובת אתר זו מורה לשירות שלנו להחזיר נתונים בפורמט JSON, במקום XML, כפי שראינו בעבר. כאשר אפשרות זו אינה קיימת, השרת ישתמש בערך ה- לְקַבֵּל כותרת, אם קיימת. כאשר אף אחד מהם אינו זמין, השרת רשאי לבחור בכל ייצוג - בדרך כלל XML או JSON.

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

6. מסקנה

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

דוגמאות לקודים, כמו תמיד, זמינות ב- GitHub.