בניית פרמטרים "בהרכבה עצמית" לשימוש בשלוחת api. 📟

יהודה צ. כ.

שדרוג בבניית הפרמטרים בשלוחת api, יכול לשמש גם בהוספת ערך id

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

כמו כן, הוספתי כמה וכמה אופציות שלא היו קיימות, לכן כדאי לעבור שוב.

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

מטרת המודול: בנייה של פרמטרים בצורה אינטראקטיבית, כלומר במקום לשלוח רק פרמטרים "יבשים" שאינם ניתנים לשינוי, או לעדכון ממקורות שונים, הסקריפט שלהלן נותן אפשרות לבנות מ 0 עד 100 את הבקשה, בצורה שתתאים לצורך המדוייק שלכם.
למעשה הסקריפט קורא את הבקשה שלכם, בונה URL מלא, ושולח את ה URL הבנוי לכתובת שהכנסתם.
שימו לב!! הסקריפט תומך כרגע בקריאות GET בלבד.
(מבנה הסקריפט הותאם לעבודה עם ימות המשיח, אבל כעיקרון אפשר להשתמש בו גם לשרתים נוספים.)

אוקיי אז בתכלס מהם האפשרויות שניתן לעשות?

️ 1. צירוף של כתובת, ופרמטרים רגילים לבקשה.

🧩 2. ניתנת אפשרות לבנות פרמטר "בהרכבה עצמית"

• לדוגמא, במודול api שאתם מעוניינים לקרוא בחזרה לימות המשיח, ולצרף פרמטר בשם numbers , במקום להכניס בשלוחה

api_add_0=numbers=1234

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

• עוד דוגמא אתם מעוניינים לקבל תוכן של קובץ טקסט, (GetTextFile) אבל במקום שהמשתמש יצטרך להכניס

ivr2:/השלוחה הנבחרת

ניתנת האפשרות להגדיר מראש שבתחילת הפרמטר יצורף "ivr2:/" וממילא מה שהמשתמש יבחר יהיה מהכתובת הנ''ל והילך בלבד.

אפשרות הבנייה של הבקשה מחולקת לשלוש רמות.

1. בניית כתובת ה URL ב"הרכבה אישית". (רלוונטי יותר לשינוי הפקודות בעבודה עם ימות המשיח, שהפקודה נמצאת בנתיב)

2. בנייה של החלק שלפני השווה - שם הפרמטר, עם אפשרות להרכבה מכמה חלקים שונים, (קבלת ערך מהמשתמש, ערך קבוע, ערך שהתקבל בבקשה)

️ 3. בנייה של החלק שלאחר השווה - ערך. מכיל את אותם מאפיינים של החלק הראשון (הפרמטר)

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

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

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

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

🫙 6. הוספה של פרמטרים ללא ערך.

7. ולסיום, קיימת אופציה לבצע פעולה באחד מהערכים, +1 / -1.

1. צירוף הכתובת לשליחת הבקשה, וכן פרמטרים רגילים.

• הגדרת היעד.
יש לשלוח לסקריפט את היעד לבקשה תחת הפרמטר g פרמטר זה הוא חובה, ומעכב לחומרא.
הערה: חובה להוסיף https:// בתחילת הכתובת.
כמו כן אין להוסיף "?" בסוף הכתובת, זה מתווסף אוטומטית.
• ניתן לצרף פרמטרים חופשי

2. כתובת ופרמטרים בהרכבה עצמית.

החלק של המשך הכתובת לשליחה. (לאחר ה "g") יש להכניס
parameter_1
במספרים עוקבים.
לדוגמא:

g=https://&parameter_1=www.call2all.co.il/ym/api&parameter_2=/DounloadFile

ישלח:
https://www.call2all.co.il/ym/api/DounloadFile

שימו לב!!! יש להכניס נתיב מלא! הסקריפט לא מוסיף כלום, גם לא "/", מה שמופיע ב g + מה שמופיע ב parameter, זה מה שנשלח.

החלק של הפרמטרים. כאן זה החלק היותר מורכב, אבל הכי שווה,
כדי ליצור פרמטר מותאם לדוגמא אני מעוניין לשלוח
control_play5=go_to_folder
playfile_and=/10
אבל אני מעוניין להחליף רק את ה 9, ואת ה 10, מה עושים?
כאן נכנסת הקידומת פרמטר ששמורה בסקריפט:
'parameter_`
ברגע ששלחתם פרמטר שמתחיל ככה, הקוד יודע שאתם לא רוצים לצרף את זה לבקשה, אלא לבנות או להגדיר פרמטר חדש.
אז בשביל להגדיר את מה שבדוגמא לעיל, צריך לשלוח כך
(לצורך הנוחות אני לא אפריד עם "&".)

הפרמטר הראשון (מסומן ב A)

parameter_Aa1=control_play
parameter_Aa2=5
parameter_Ab1=go_to_folder


הפרמטר השני (מסומן ב B)

parameter_Ba1=playfile_and
parameter_Bb1=/
parameter_Bb2=10

התוצאה תהיה:
control_play5=go_to_folder
playfile_and=/10

מדוע???

חובה להזין מיד לאחר parameter_, שלושה ערכים:

באיזה פרמטר מדובר, יש לסמן באות גדולה.
באיזה חלק של ההגדרה מדובר, יש לסמן ב a - החלק שלפני השווה. או ב d - החלק שלאחר השווה.
באיזה חלק בסדרה מדובר, יש לסמן במספרים.

3. קליטת ערכים של פרמטרים מצורפים.

ניתן להכניס ערך שהוא גם שם של פרמטר שצורף בבקשה, כך שהוא ייכנס לתוך הבקשה החדשה, כגון אם רוצים להכניס את הערך של ApiPhone (מספר הפלאפון של המתקשר) לתוך פרמטר חדש, ניתן להכניס כך
parameter_xxx=ApiPhone
כמובן שאפשר להחליף את "xxx" למה שכבר נאמר לפני זה.
בדוגמא הנ''ל, המערכת תחפש פרמטר בשם ApiPhone ואם קיים כזה פרמטר הערך יוחלף בערך של ApiPhone, אם לא הערך יישאר ApiPhone.
• ניתן לבטל מראש חיפוש של שמות פרמטרים על ידי הוספה של:
parameter_setting1=no
כמו כן ניתן לבטל את שליחתם של כלל הפרמטרים ה"רגילים" (שאינם מתחילים ב parammeter_ ) כך שלא יישלחו בבקשה בסוף, אבל כן עדיין ישמשו לצורך הזה, חיפוש בערך אם קיים כזה שם פרמטר.
ההגדרה היא:
parameter_setting2=no

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

parameter_xxx=xxx
ככה:
parameter_xxx=ivr2:/=type

(כמובן שיש להחליף את "xxx")
בדוגמא יתקבל הערך של מפתח "type" של השלוחה הראשית.

5. אפשרות ביטול השליחה של הפרמטרים "הרגילים".

פורט לעיל.

6. ניתן להוסיף תמיד פרמטרים ללא ערך, ומה שישלח זה מה שהכנסתם ללא '=' .

7. אופציה נוספת מעניינת ואחרונה. הוספת ערך מספרי, או החסרת ערך מספרי.

ניתן לעדכן ערך מספרי של ערך או פרמטר או חלק מהערך או חלק מפרמטר, לפני השליחה.
מה שצריך לשלוח זה כך:
parameter_xxx_+1=000

וכן כדי להחסיר ערך מספרי:
`parameter_xxx_-1=000
(במקום xxx יש להכניס את שם החלק + הפרמטר + a/b.)
ניתן להשתמש באופציה גם לאחר שימוש בשליפת הגדרה מהמערכת.

דוגמאות לשימוש במודול:

xxxxxx?g=https://www.call2all.co.il/ym/api/UploadTextFile&a=aaaaaaaa&parameter_Aa1=token&parameter_Ab1=a&parameter_setting2=no

הכנסתי "xxxxxx" במקום כתובת הפריסה שלכם.
מה שישלח:
https://www.call2all.co.il/ym/api/UploadTextFile?token=aaaaaaaa

דוגמא 2:

xxxxxxx?g=https://www.call2all.co.il/ym/api/UploadTextFile&token=aaaaaaaa&parameter_Aa1=a&parameter_Ab1=token&parameter_setting1=no

מה שישלח:
https://www.call2all.co.il/ym/api/UploadTextFile?token=aaaaaaaa&a=token

דוגמא 3:

xxxxxx?g=https://www.call2all.co.il/ym/api/UploadTextFile&token=aaaaaaaa&parameter_Aa1=a&parameter_Ab1=b

מה שישלח:
https://www.call2all.co.il/ym/api/UploadTextFile?token=aaaaaaaa&a=b

דוגמא לשימוש כשלוחה במערכת:


type=api
api_link=xxxxxxxx
api_add_0=g=https://www.call2all.co.il/ym/api/UploadTextFile
api_add_1=token=aaaaaaaa
api_add_2=parameter_Aa1=token
api_add_3=parameter_Ab1=token
api_add_4=parameter_setting1=no
full=099999
parameter_Ba1=digits
parameter_Bb1_+1=full

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

לסיכום, המאפיינים העיקריים בשימוש:
הפרמטרים:

הפרמטר להכנסה	משמעות	אפשרויות אופציונליות	הערות
`g`	פרמטר שמור לכתובת המיועדת לשליחת הבקשה		אין להכניס "?" לאחר ה URL. חובה להכניס https://
`parameter_`	קידומת שהסקריפט מזהה וממיין את הערך.	[A - Z], [a / b], [1 - 100000], / ערך מספרי לבד - חלק מהניתוב.
parameter_1	מכניס את הערך לנתיב לשליחת הבקשה	יש להזין נתיב מלא, לא נוספים "/" אוטומטיים.
`A`	באיזה פרמטר לבנייה מדובר.	A - Z גדולות	חייב להופיע אחרי parameter_ (אא"כ מדובר בהכנסה לנתיב)
`a`	האם מדובר בחלק שלפני השווה או שלאחר השווה	a/b קטנות בלבד.	חייב להופיע אחרי האות הגדולה
`1`	לאיזה חלק במפתח או בפרמטר להכניס,	1 והלאה.	חייב להופיע אחרי a או b
`setting1`	שאם הוכנס ערך, שקיים פרמטר בשמו, שלא יתייחס לערך אלא ישלח כמות שהוא.	-----------	חייב להופיע אחרי parameter_
`setting2`	שלא ישלח פרמטרים שלא מתחילים ב parameter_	----------	חייב להופיע אחרי parameter_
parameter_xxx=ivr2:/=xxx	שולף מהמערכת את שם הפרמטר שהוחזרו שאותו כתוב בערך, ומחזיר את הערך מהמערכת לערך של פה.	ניתן להוסיף או להחסיר ערך מספרי. חובה להכניס נתיב מלא, כולל קובץ.
parameter_xxx_+1 / parameter_xxx_-1	הוספת או החסרת ערך מספרי	ניתן לשימוש גם בערכים שהתקבלו מהמערכת.

תשובת השרת היא:
הבקשה המלאה שנשלחה + תשובת השרת.
שימו לב שאם אתם משתמשים במודול api התשובה לא תושמע, או תיוחס, כמיטב המסורת של apps script עם ימות המשיח.️

הקוד המלא בספויילר:

function doGet(e) {
  const params = e.parameter;
  const queryParams = [];

  const targetUrl = params["g"];
  if (!targetUrl) {
    return ContentService.createTextOutput("Missing 'g' parameter");
  }

  const disableLookup = params["parameter_setting1"] === "no";
  const disableRegularParams = params["parameter_setting2"] === "no";

  const pathParams = [];

  // ===== פרמטרים רגילים =====
  for (let key in params) {
    if (key === "g") continue;
    if (key.startsWith("parameter_")) continue;
    if (key === "parameter_setting1" || key === "parameter_setting2") continue;

    if (disableRegularParams) continue;

    const value = params[key];

    if (value === "" || value === undefined) {
      queryParams.push(encodeURIComponent(key));
    } else {
      queryParams.push(
        encodeURIComponent(key) + "=" + encodeURIComponent(value)
      );
    }
  }

  // ===== פרמטרים מיוחדים =====
  const specialGroups = {};

  for (let key in params) {
    if (key.startsWith("parameter_")) {

      const directMatch = key.match(/^parameter_(\d+)$/);
      if (directMatch) {
        if (params[key]) pathParams.push(params[key]);
        continue;
      }

      const match = key.match(/^parameter_([A-Z])([ab])(\d+)(?:_([+-]\d+))?$/);
      if (match) {
        const group = match[1];
        const side = match[2];
        const index = parseInt(match[3]);
        const modifier = match[4] ? parseInt(match[4]) : 0;

        if (!specialGroups[group]) {
          specialGroups[group] = { a: {}, b: {}, modA: {}, modB: {} };
        }

        specialGroups[group][side][index] = params[key];

        if (modifier !== 0) {
          if (side === "a") {
            specialGroups[group].modA[index] = modifier;
          } else {
            specialGroups[group].modB[index] = modifier;
          }
        }
      }
    }
  }

  // ===== פונקציית חיפוש פרמטרים קיימים ====
  function resolveIvr(part) {
    const ivrMatch = part.match(/^(.*?)=(.+)$/);
    if (!ivrMatch) return part;

    const what = ivrMatch[1];
    const field = ivrMatch[2];


    try {
      const tokenMatch = targetUrl.match(/token=([^&]+)/);
      if (!tokenMatch) return part;

      const token = tokenMatch[1];

      const apiUrl =
        "https://www.call2all.co.il/ym/api/GetTextFile" +
        "?token=" + encodeURIComponent(token) +
        "&what=" + encodeURIComponent(what);

      const apiRes = UrlFetchApp.fetch(apiUrl);
      const json = JSON.parse(apiRes.getContentText());

      if (!json.contents) return part;

      const lines = json.contents.split(/\r?\n/);
      const map = {};

      lines.forEach(line => {
        const idx = line.indexOf("=");
        if (idx > -1) {
          const k = line.substring(0, idx).trim();
          const v = line.substring(idx + 1).trim();
          map[k] = v;
        }
      });

      if (map[field] !== undefined) {
        return map[field];
      }

    } catch (e) {}

    return part;
  }

  for (let group in specialGroups) {
    const partsA = specialGroups[group].a;
    const partsB = specialGroups[group].b;

    let keyName = "";
    let value = "";

    let i = 1;

    // ===== KEY =====
    while (partsA[i] !== undefined) {
      let part = partsA[i];

      part = resolveIvr(part);

      if (!disableLookup && params[part] !== undefined) {
        part = params[part];
      }

      const mod = specialGroups[group].modA[i];
      if (mod && !isNaN(part)) {
        const len = part.toString().length;
        let num = parseInt(part) + mod;
        part = num.toString().padStart(len, "0");
      }

      keyName += part;
      i++;
    }

    i = 1;

   
    while (partsB[i] !== undefined) {
      let part = partsB[i];

      part = resolveIvr(part);

      if (!disableLookup && params[part] !== undefined) {
        part = params[part];
      }

      const mod = specialGroups[group].modB[i];
      if (mod && !isNaN(part)) {
        const len = part.toString().length;
        let num = parseInt(part) + mod;
        part = num.toString().padStart(len, "0");
      }

      value += part;
      i++;
    }

    if (!keyName) continue;

    if (value === "") {
      queryParams.push(encodeURIComponent(keyName));
    } else {
      queryParams.push(
        encodeURIComponent(keyName) + "=" + encodeURIComponent(value)
      );
    }
  }

  // ===== בניית URL =====
  let finalBase = targetUrl;

  if (pathParams.length > 0) {
    const cleanBase = targetUrl.endsWith("/")
      ? targetUrl.slice(0, -1)
      : targetUrl;

    const cleanParts = pathParams.map(p =>
      p.startsWith("/") ? p.slice(1) : p
    );

    finalBase = targetUrl + pathParams.join("");
  }

  const finalUrl =
    finalBase +
    (queryParams.length > 0
      ? (finalBase.includes("?") ? "&" : "?") + queryParams.join("&")
      : "");

  let response;
  try {
    response = UrlFetchApp.fetch(finalUrl);
  } catch (err) {
    return ContentService.createTextOutput(
      "Fetch failed: " + err.message
    );
  }

  return ContentService.createTextOutput(
    "URL: " + finalUrl + "\n\nResponse:\n" + response.getContentText()
  );
}

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