הסבר על ה-API של Service Compiler Service

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

סקירה כללית

כדי לבקש קוד הידור או מידע אחר משירות מהדר סגירה, עליכם לשלוח בקשת HTTP POST אל כתובת ה-URL https://closure-compiler.appspot.com/compile. גוף הבקשה חייב להכיל את הפרמטרים המפורטים בפרמטרים נדרשים של בקשה, והוא יכול לכלול גם את הפרמטרים האופציונליים שרשומים בפרמטרים אופציונליים של בקשה.

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

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

פרמטרים של בקשות

פרמטרים נדרשים של בקשה

js_code או code_url

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

הפרמטר js_code חייב להיות מחרוזת שמכילה JavaScript, כמו alert('hello').

הפרמטר code_url חייב להכיל את כתובת ה-URL של קובץ JavaScript. אפשר לכלול מספר פרמטרים של code_url כדי לציין כמה קובצי קלט.

compilation_level

אפשר לעיין במסמכים של compilation_level בסימונים ואפשרויות.

output_format

הפורמט של הפלט של שירות מהדר סגירה. קיימים שלושה פורמטים אפשריים של פלט:

xml

פורמט הפלט של xml עוטף את המידע המבוקש ב-XML חוקי.

פלט ה-XML נראה כך:

        <compilationResult>
          <compiledCode>var a="hello";alert(a);</compiledCode>
          <statistics>
            <originalSize>98</originalSize>
            <compressedSize>35</compressedSize>
            <compileTime>0</compileTime>
          </statistics>
        </compilationResult>
      

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

אם כוללים פרמטר output_info עם הערך warnings והמהדר יוצר אזהרה, הפלט יכלול תג warnings:

        <compilationResult>
         ...
         <warnings>
           <warning type="JSC_NO_SIDE_EFFECT" file="default.js" lineno="12" charno="3"  line="delete 1;">warning 1</warning>
           <warning type="JSC_UNUSED_VAR" file="default.js" lineno="13" charno="13" line="delete 1;">warning 2 </warning>
         </warnings>
          ...
        </compilationResult>
      

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

        <compilationResult>
          ...
          <errors>
            <error type="JSC_NO_SIDE_EFFECT" file="default.js" lineno="12" charno="3"  line="var x=-'hello';">error 1 </error>
            <error type="JSC_UNUSED_VAR" file="default.js" lineno="13" charno="13" line="var x=-'hello'">error 2 </error>
          </errors>
          ...
        </compilationResult>
      

המאפיינים file, line ו-col של התגים error ו-warning מציינים איפה אירעה השגיאה ב'כלי מהדר סגירה'.

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

        <compilationResult>
          <serverErrors>
            <error code="1">Over quota</error>
          </serverErrors>
        </compilationResult>
      

json

פורמט הפלט של json עוטף את המידע המבוקש במחרוזת של סימון אובייקט JavaScript (JSON). ההערכה של המחרוזת הזו כ-JavaScript מחזירה אובייקט JavaScript.

פלט ה-JSON נראה כך:

{
"compiledCode":/* raw code here */,
{"errors": [
  {"charno":4321,
   "error":"ERROR: You failed.",
   "lineno":1234,
   "file":"default.js",
   "type":"ERROR_TYPE",
   "line":"var x=-'hello';"}],
"warnings": [
  {"charno":4321,
   "lineno":1234,
   "file":"default.js",
   "type":"ERROR_TYPE",
   "warning":"Warning: You did something wrong!",
   "line":"delete 1;"}]
"serverErrors":[
  {"code":123,"error":"Over quota"}
  ],
"statistics":{
  "originalSize":10,
  "compressedSize":3000
  "compileTime":10
  }
}
      

פורמט ה-JSON דומה לפורמט ה-XML: כל תג בפלט ה-XML תואם לנכס בעל שם זהה באובייקט ה-JSON.

text

פורמט הפלט של text מחזיר טקסט גולמי ללא תגים או סוגריים של JSON. אם output_info כולל compiled_code, הטקסט מכיל JavaScript. אם השדה output_info כולל את warnings, הטקסט מכיל הודעות אזהרה. אם הערך output_info כולל את הערך statistics, הטקסט מכיל נתונים סטטיסטיים.

ערך הפרמטר output_format מקבל ערך text כברירת מחדל.

output_info

סוג הפלט הרצוי של המהדר. יש ארבעה סוגים אפשריים של פלט:

compiled_code

גרסה דחוסה ומותאמת של ה-JavaScript שהזנת.

warnings

הודעות שמציינות באגים אפשריות ב-JavaScript.

errors

הודעות שמציינות שגיאות תחביר או שגיאות אחרות ב-JavaScript.

statistics

מידע על מידת הדחיסה של מהדק החסימות. לגבי פלט xml, שירות 'סגירת אוסף' מחזיר נתונים סטטיסטיים בפורמט הבא:

        <compilationResult>
          ...
          <statistics>
            <firstStatisticName>24</firstStatisticName>
            <secondStatisticName>15</secondStatisticName>
          </statistics>
        </compilationResult>
      

פרמטרים אופציונליים של בקשות

js_externs

הערך של הפרמטר הזה צריך להיות קוד JavaScript שמצהיר על שמות פונקציות או סמלים אחרים. יש להשתמש ב-js_externs כדי לשמור סמלים שמוגדרים מחוץ לקוד ההידור. הפרמטר js_externs נכנס לתוקף רק אם משתמשים ב-compilation_level של ADVANCED_OPTIMIZATIONS. מידע נוסף זמין באוסף המתקדם.

externs_url

הערך של הפרמטר הזה צריך להיות כתובת ה-URL של קובץ שמכיל JavaScript שמצהיר על שמות פונקציות או סמלים אחרים. הסמלים שמופיעים בקובץ הזה נשמרים בדיוק באותו אופן כמו סמלים שרשומים ישירות בפרמטר js_externs. הפרמטר externs_url משפיע רק אם משתמשים ב-compilation_level מתוך ADVANCED_OPTIMIZATIONS. מידע נוסף זמין באוסף המתקדם.

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

exclude_default_externs

כברירת מחדל, שירות מהדרים 'סגירה' משתמש בקובץ exten סטנדרטי שמצהיר על סמלים נפוצים שהוגדרו באופן חיצוני כמו document וכל השיטות שבו. לא רוצה להשתמש בתוספים החיצוניים האלה? מומלץ לכלול בבקשה פרמטר exclude_default_externs עם הערך true.

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

output_file_name

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

https://closure-compiler.appspot.com/code/bf067f356d510e1c7b81347eb84f65d2/[value of output_file_name]

formatting

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

use_closure_library

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

הפרמטר use_closure_library מקבל את ערך ברירת המחדל false.

warning_level

אפשר לעיין במסמכים של warning_level בסימונים ואפשרויות.

language

אפשר למצוא תיעוד של האפשרות המקבילה בlanguage_in בדף סימונים ואפשרויות.

language_out

אפשר לעיין במסמכים של language_out בסימונים ואפשרויות.

rewrite_polyfills

אפשר לעיין במסמכים של rewrite_polyfills בסימונים ואפשרויות.

use_types_for_optimization

אפשר לעיין במסמכים של use_types_for_optimization בסימונים ואפשרויות.

הודעות שגיאה

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

קוד שגיאה	הודעת שגיאה	משמעות
2	מצב פלט לא ידוע.	הערך של הפרמטר output_format שונה מ-xml, json או text.
4	רמת דחיסה לא ידועה.	הערך של הפרמטר compilation_level שונה מ-WHITESPACE_ONLY, SIMPLE_OPTIMIZATIONS או ADVANCED_OPTIMIZATIONS.
8	נתוני POST גדולים מדי.	הגודל של הנתונים ששלחת לשירות 'מהדר סגירה' גדול מ-200,000 בייטים. ממשק המשתמש של Compiler וגם קריאות ה-API שלך משתמשים בבקשת HTTP POST כדי לתקשר עם השירות, וסך כל הנתונים בבקשה לא יכול לחרוג מ-200,000 בייטים. על קריאות ל-API, המגבלה הזו חלה על הטקסט הכולל בכל הפרמטרים של הבקשות. בממשק המשתמש של מהדר סגירה, ההגבלה הזו חלה על הכמות הכוללת של טקסט גם בקוד המקור וגם באפשרויות המהדר, כמו @code_url. אם הבקשה שלך גדולה מדי, עליך להעביר את קוד המקור לקבצים נפרדים ולהפנות אליהם באמצעות @code_url, או להשתמש באפליקציה 'מהדר סגירה' במחשב המקומי.
9	הקובץ גדול מדי.	הכמות הכוללת של קוד מכל code_url הקבצים, externs_url הקבצים, כל הקוד js_code והקוד של js_externs חורגת מ-1024,000 בייטים.
10	לא ניתן לאחזר תוכן מכתובת ה-URL.	אירעה שגיאה כשהשירות 'מהדר סגירה' ניסה לאחזר קובץ JavaScript שצוין בפרמטר code_url או קובץ extens שצוין בפרמטר externs_url. ודאו שכתובת ה-URL נכונה ושההרשאות של הקובץ מאפשרות להציג אותה.
12	הפורמט של כתובת ה-URL שגוי.	הערך של הפרמטר code_url או של הפרמטר externs_url לא תקין.
13	אין נתוני פלט שאפשר ליצור, אבל נשלחה בקשה לאיסוף.	לא צוין פרמטר output_info.
14	ערך היציאה_של פלט לא ידוע	הערך של פרמטר output_info שונה מ-compiled_code, warnings או statistics.
16	רמת אזהרה לא ידועה	הערך של הפרמטר warning_level שונה מ-QUIET, DEFAULT או VERBOSE.
17	אפשרות עיצוב לא ידועה.	הערך של הפרמטר formatting שונה מ-pretty_print.
18	פרמטר לא ידוע בבקשת HTTP	בקשת ה-HTTP מכילה פרמטר שאינו אחד מאלה שמפורטים במסמך הזה.
19	ערך לא חוקי של file_file_name	שם קובץ הפלט מכיל תו מספר, אות, נקודה, קו תחתון או מקף, או שהוא מכיל שתי נקודות עוקבות (..)
22	בוצעו יותר מדי מהדרים לאחרונה. נסו שוב מאוחר יותר.	שלחת מהדרים רבים מדי מהמחשב שלך. לאחר שעה, תוכלו שוב לבצע מהדרים.
23	חריג מהדר (עם מעקב לאחור)	המהדר קרס. הטקסט של השגיאה יכלול פרטים שיעזרו ל-Google לאתר את הבעיה.
24	סוג המשאב שהזנת לא נתמך	סוג המשאב אינו http: ולכן קובץ הקלט לא יאוחזר.