# 腳本 原文鏈接 : [http://www.apache.wiki/display/Elasticsearch/Scripting](http://www.apache.wiki/display/Elasticsearch/Scripting)（修改該鏈接為官網對應的鏈接） 譯文鏈接 : [http://www.apache.wiki/display/Elasticsearch/Scripting](http://www.apache.wiki/display/Elasticsearch/Scripting) 貢獻者 :?[阿叩](/display/~luanqing)，[ApacheCN](/display/~apachecn)，[Apache中文網](/display/~apachechina) MarkDown文件：[Scripting.md](https://github.com/aqlu/elasticsearch_translate/blob/master/Modules/Scripting.md) ## 腳本 腳本模塊能夠幫你通過腳本來自定義表達式求值。例如，你可以使用腳本作為搜索請求的一部分返回“腳本字段”或自定義一個評分查詢。 默認腳本語言為[Painless](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting-painless.html)。您能夠通過添加`lang`插件來啟用其他語言編寫的腳本。任何使用腳本的地方，您都可以通過設置`lang`參數來指定腳本的語言。 ## 普通語言 這些語言可以用于任何的腳本API，并給予了最大的靈活性。 | 語言 | 沙盒 | 所需插件 | | --- | --- | --- | | painless | yes | 內置 | | groovy | no | 內置 | | javascript | no | [lang-javascript](https://www.elastic.co/guide/en/elasticsearch/plugins/5.3/lang-javascript.html) | | python | no | [lang-javascript](https://www.elastic.co/guide/en/elasticsearch/plugins/5.3/lang-javascript.html) | ## 專業語言 這些語言不太靈活，但對于某些任務通常有更高的性能。 | 語言 | 沙盒 | 所需插件 | 用途 | | --- | --- | --- | --- | | [expression](/pages/viewpage.action?pageId=9405371) | yes | 內置 | 快速自定義評分與排序 | | [mustache](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html) | yes | 內置 | 模板 | | [java](/pages/viewpage.action?pageId=9405376) | n/a | 自己寫 | 專業API | **腳本與安全（警告）** 語言在設計時是考慮到安全沙盒的。然而，非沙盒語言可能是一個安全問題，請閱讀[腳本與安全](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting-security.html)來獲取詳細信息。 ? ?腳本使用 ? ??在es API中支持腳本的地方，語法遵循相同的模式： ? ? "script": { ?"lang": "...", （1） "inline" | "stored" | "file": "...", （2） "params": { ... } （3） } （1）寫入腳本的語言，默認為painless。 （2）腳本可以指定為?`inline`,?`stored`, or?`file`. ?（3）?傳遞給腳本的命名參數。 eq:下面腳本是查找請求 返回scripted field: PUT my_index/my_type/1 { "my_field": 5 } GET my_index/_search { "script_fields": { "my_doubled_field": { "script": { "lang": "expression", "inline": "doc['my_field'] * multiplier", "params": { "multiplier": 2 } } } } } 參數 lang 指定腳本寫入的語言，你可以設置任何腳本語言，可以通過改變config 文件下 elasticsearch.yml 設置成script.default_lang 合適的語言 inline, stored, file 指定腳本的源 inline腳本入上面eg所示 stored 指定存儲在集群(see Stored Scripts 超連接)并從config / scripts目錄中的文件檢索文件腳本（請參閱文件腳本）。 雖然眾多表達式和painless 語言可以作為inline或存儲的腳本配置即可用，但其他例如groovy的語言只能被指定為文件，除非您首先調整默認的腳本安全設置。 params 指定作為變量傳遞到腳本中的任何命名參數。 prefer 參數 Elasticsearch第一次使用腳本 編譯并且存在在cache中 可能是一個復雜的過程 如果您需要將變量傳遞到腳本中，那么您應該將它們作為命名參數傳遞，而不是將其轉換為腳本本身的編碼。 eg，如果您想要實現不同的乘數乘以一個字段值，則不要將乘法器編碼在腳本中 "inline": "doc['my_field'] * 2" 命名參數傳遞： "inline": "doc['my_field'] * multiplier", "params": { "multiplier": 2 } 每次乘法器更改時，必須重新編譯一次版本。 如果編譯了太多的獨特腳本，Elasticsearch將會以circuit_breaking_exception錯誤拒絕動態腳本。 默認情況下，每分鐘最多可編譯15個內聯腳本。 您可以通過設置script.max_compilations_per_minute來動態更改此設置。 file 基本腳本 為了提高安全性，只能在集群中每個節點上存儲的腳本文件中指定語言。 文件腳本必須保存在scripts 目錄中，其默認位置取決于是否使用zip / tar.gz（$ ES_HOME / config / scripts /），RPM或Debian軟件包。 默認值可以通過path.scripts設置更改。 默認情況下語言是：painless, expression, and mustache（用于搜索和查詢模板）。 腳本目錄中放置的任何文件將在節點啟動后自動編譯，every 60 seconds thereafter。 該文件應該命名如下：{script-name}。{lang}。 例如，以下示例創建一個名為calculate-score的calculate-score： cat "log(_score * 2) + my_modifier" > config/scripts/calculate-score.groovy 腳本可以使用下面的 GET my_index/_search { "query": { "script": { "script": { "lang": "groovy", （1） "file": "calculate-score", (2) "params": { "my_modifier": 2 } } } } } 1.腳本的suffix（后綴） 2.file的名字 腳本目錄可能包含子目錄，在這種情況下，目錄的層次結構將被連接。 group1 / group2 / my_script.groovy中的腳本應該使用group1_group2_myscript作為文件名。 自動腳本重載 腳本目錄將每60秒重新掃描一次（可以使用resource.reload.interval設置進行配置），新腳本，已更改或已刪除的腳本將從腳本緩存中進行編譯，更新或刪除。 腳本重新加載可以通過將script.auto_reload_enabled設置為false來完全禁用。 腳本存儲 腳本可以使用_scripts終點存儲在集群狀態并從集群狀態中檢索。 棄用的命名空間 使用lang和id作為唯一標識符的存儲腳本的命名空間已被棄用。存儲腳本的新命名空間只能使用id。存儲的腳本具有相同的id，但不同的lang的將不再允許在6.0。要遵守存儲腳本的新命名空間，現有存儲的腳本應該被刪除并重新放置。任何共享id但具有不同“lang”的腳本將需要重新命名。例如，請執行以下操作： “id”：“example”，“lang”：“painless”“id”：“example”，“lang”：“表達式” 上述腳本將在新的命名空間下沖突，因為id是相同的。至少有一個必須被重新命名才能遵守id的新命名空間。 作為最后的注意事項，存儲的搜索模板和存儲的腳本共享相同的命名空間，因此，如果搜索模板與存儲的腳本具有相同的標識，則必須使用delete和put請求重新命名其中的一個。 請求的eg /_scripts/{id} 備注：id為唯一值、 在群集狀態中存儲一個名為calculate-score的 painless 腳本： POST _scripts/calculate-score { "script": { "lang": "painless", "code": "Math.log(_score * 2) + params.my_modifier" } } 和上面一樣的效果的 GET _scripts/calculate-score 存儲腳本可以利用下面的例子 GET _search { "query": { "script": { "script": { "stored": "calculate-score", "params": { "my_modifier": 2 } } } } } deleted DELETE _scripts/calculate-score 查詢緩存 默認情況下，所有腳本都被緩存，因此只有當更新發生時才需要重新編譯。 文件腳本保留靜態緩存，并始終駐留在內存中。 內聯和存儲的腳本都存儲在可以驅逐駐留腳本的緩存中。 默認情況下，腳本沒有時間到期，但您可以使用script.cache.expire設置更改此行為。 您可以使用script.cache.max_size設置來配置此緩存的大小。 默認情況下，緩存大小為100。 存儲腳本的大小限制為65,535字節。 這可以通過設置script.max_size_in_bytes設置來更改，以增加限制，但是如果腳本真的很大，那么應該考慮替代native 腳本。 請求文檔文件和特殊變量 根據使用腳本的位置，它可以訪問某些特殊變量和文檔字段。 cix._source 反問文檔_source field cix.op index or delete ctx._index document meta-fields 訪問 查詢聚合腳本 除了每個搜索命中執行一次的腳本字段外，搜索和聚合中使用的腳本將針對可能與查詢或聚合匹配的每個文檔執行一次。 根據你有多少文件，這可能意味著數百萬或數十億的執行：這些腳本需要快！ 可以使用文檔值或存儲的字段或_source字段從腳本訪問字段值，這些位置如下所述。 腳本還可以訪問文檔的相關性_score，并通過實驗_index變量訪問高級文本評分的術語統計信息。 訪問score（評分）文檔的腳本 在function_score查詢，基于腳本的排序或聚合中使用的腳本可以訪問表示文檔當前相關性分數的_score變量。 以下是使用function_score查詢中的腳本更改每個文檔的相關性_score的示例： PUT my_index/my_type/1 { "text": "quick brown fox", "popularity": 1 } PUT my_index/my_type/2 { "text": "quick fox", "popularity": 5 } GET my_index/_search { "query": { "function_score": { "query": { "match": { "text": "quick brown fox" } }, "script_score": { "script": { "lang": "expression", "inline": "_score * doc['popularity']" } } } } } doc values 到目前為止，從腳本訪問字段值最快最有效的方法是使用doc ['field_name']語法，它從doc值檢索字段值。 文檔值是一個列字段值存儲，默認情況下在除分析文本字段之外的所有字段上啟用。 PUT my_index/my_type/1 { "cost_price": 100 } GET my_index/_search { "script_fields": { "sales_price": { "script": { "lang": "expression", "inline": "doc['cost_price'] * markup", "params": { "markup": 0.2 } } } } } 如果字段為多值，則文檔值只能返回“簡單”字段值，如數字，日期，地理位置，術語等，或這些值的數組。 它不能返回JSON對象。 文檔值和text 字段 如果啟用了fielddata，則doc ['field']語法也可用于分析的文本字段，但BEWARE：在文本字段上啟用fielddata需要將所有術語加載到JVM堆中，這可能非常昂貴 內存和CPU。 從腳本訪問文本字段很少有意義。 存儲字段和_source 存儲字段 - 明確標記為“store”的字段：true - 可以使用_fields ['field_name']。或_fields ['field_name']。值語法訪問。 可以使用_source.field_name語法訪問真正只是特殊存儲字段的文檔_source。 _source被加載為map-of-maps，因此可以訪問對象字段內的屬性，例如.first。 prefer 儲存字段文檔值 存儲的字段（包括存儲的_source字段）比doc值慢得多。 它們被優化為每個結果返回幾個字段，而doc值被優化用于訪問許多文檔中特定字段的值。 在從搜索結果生成前十個匹配的腳本字段時使用_source或存儲字段是有意義的，但對于其他搜索和聚合用例，總是更喜歡使用doc值。 eg PUT my_index { "mappings": { "my_type": { "properties": { "title": { （1） "type": "text" }, "first_name": { "type": "text", "store": true }, "last_name": { "type": "text", "store": true } } } } } PUT my_index/my_type/1 { "title": "Mr", "first_name": "Barry", "last_name": "White" } GET my_index/_search { "script_fields": { "source": { "script": { "inline": "params._source.title + ' ' + params._source.first_name + ' ' + params._source.last_name" }（2） }, "stored_fields": { "script": { "inline": "params._fields['first_name'].value + ' ' + params._fields['last_name'].value" } } } } 1.標題字段不存儲，因此不能與_fields []語法一起使用。 2.標題字段仍然可以從_source訪問。 stored 和_source 比較 _source字段只是一個特殊的存儲字段，因此性能與其他存儲字段的性能相似。 _source提供對索引的原始文檔主體的訪問（包括區分空值和空字段的能力，單值數組從平坦標量等）。 使用存儲字段而不是_source字段唯一有意義的是，當_source非常大時，訪問一些小的存儲字段而不是整個_source成本較低。 腳本的安全 您不能用root用戶身份運行Elasticsearch，因為這將允許腳本在您的服務器上訪問或執行任何操作，而不受限制。 您不應該將Elasticsearch直接顯示給用戶，而是在其間具有代理應用程序。 如果您打算將Elasticsearch直接顯示給用戶，那么您必須決定是否信任足夠的腳本來運行腳本，并應用相應的安全措施。 script.*設置允許對哪些腳本語言（例如，groovy，painless）被允許運行在哪個上下文（例如 search，aggs，update）以及允許腳本來源的位置（即 inline stored file）。進行細粒度控制 例如，以下設置可將存儲的更新腳本用于groovy： script.engine.groovy.inline.update: true 存在不太細粒度的設置，允許您為所有源，所有語言或所有上下文啟用或禁用腳本。 以下設置為所有上下文中的所有語言啟用內聯和存儲的腳本： script.inline: true script.stored: true 上述設置意味著任何可以向Elasticsearch實例發送請求的人都可以運行任何他們選擇的腳本！ 這是一個安全風險，可能會導致您的Elasticsearch集群受到威脅。 腳本源設置 腳本可能會被啟用或禁用，具體取決于它們的來源：內聯，存儲在群集狀態，或者來自集群中每個節點上的文件。 這些設置中的每一個都需要以下值之一： false 腳本停止 true 腳本啟動 默認是 script.inline: false script.stored: false script.file: true 全局腳本設置會影響到 mustache 腳本語言。 搜索模板內部使用mustache 語言，并且默認情況下仍將啟用sandboxed， 但會根據elasticsearch.yml中指定的細粒度設置啟用/禁用。 腳本文檔的設置 還可以在Elasticsearch API的不同上下文中啟用或禁用腳本。 支持的上下文是： aggs：聚合 search：查詢 update 更新 plugin 插件 插件還可以定義他們使用腳本的自定義操作，而不是使用通用插件類別。 這些操作可以以下列形式引用：$ {pluginName} _ $ {operation}。 以下示例將禁用更新和插件操作的腳本，而不管腳本源或語言如何。 腳本仍然可以從沙盒語言執行，作為聚合，搜索和插件執行的一部分，因為上述默認值仍然被應用。 script.update: false script.plugin: false 細粒度腳本設置 首先，按順序應用上述的高級腳本設置（上下文設置優先于源設置）。 然后，包含腳本語言的細粒度設置優先于任何高級設置。 細粒度設置的格式如下： script.engine.{lang}.{source}.{context}: true|false and script.engine.{lang}.{inline|file|stored}: true|false eg： script.inline: false 1 script.stored: false 2 script.file: false 3 script.engine.groovy.inline: true 4 script.engine.groovy.stored.search: true 5 script.engine.groovy.stored.aggs: true 6 script.engine.mustache.stored.search: true 7 1關閉腳本的源 4啟動inline腳本運行 5啟動存儲查詢聚合 7啟動存儲mustache 查詢 Java安全管理 默認情況下啟用Java Security Manager運行Elasticsearch。 Elasticsearch中的安全策略將授予每個類的權限鎖定到操作所需的最低限度。 這樣做的好處是它嚴重限制了黑客可用的攻擊向量。 限制權限對于Groovy和Javascript這樣的腳本語言尤為重要，這些腳本語言旨在執行Java本身可以完成的任何操作，包括寫入文件系統，將套接字打開到遠程服務器等。 腳本類加載器白名單 腳本語言只允許加載出現在可以在org.elasticsearch.script.ClassPermission中找到的編碼的白名單中的類。 在腳本中，嘗試加載未顯示在白名單中的類可能會導致ClassNotFoundException異常，例如此腳本： GET _search { "script_fields": { "the_hour": { "script": "use(java.math.BigInteger); new BigInteger(1)" } } } 返回下面 { "reason": { "type": "script_exception", "reason": "failed to run inline script [use(java.math.BigInteger); new BigInteger(1)] using lang [groovy]", "caused_by": { "type": "no_class_def_found_error", "reason": "java/math/BigInteger", "caused_by": { "type": "class_not_found_exception", "reason": "java.math.BigInteger" } } } } 然而，類加載器問題也可能導致更難以解釋異常。 例如，這個腳本： use(groovy.time.TimeCategory); new Date(123456789).format('HH') 返回下面 { "reason": { "type": "script_exception", "reason": "failed to run inline script [use(groovy.time.TimeCategory); new Date(123456789).format('HH')] using lang [groovy]", "caused_by": { "type": "missing_property_exception", "reason": "No such property: groovy for class: 8d45f5c1a07a1ab5dda953234863e283a7586240" } } } 處理Java安全管理器問題 如果您遇到Java安全管理器的問題，您有兩個解決這些問題的選項： 修復安全問題 最安全和最安全的長期解決方案是更改導致安全問題的代碼。 我們認識到這可能需要時間才能正確進行，因此我們提供以下兩種選擇。 自定義類加載器whitelistedit 可以通過調整本地Java安全策略來定制類加載器白名單： 系統范圍：$ JAVA_HOME/lib/security /java.policy， 僅用于彈性搜索用戶：/home/elasticsearch/.java.policy 通過將系統屬性添加到jvm.options配置中：-Djava.security.policy = someURL，或 通過帶有-Djava.security.policy = someURL的ES_JAVA_OPTS環境變量： export ES_JAVA_OPTS="${ES_JAVA_OPTS} -Djava.security.policy=[file:///path/to/my.policy](file:///path/to/my.policy)` ./bin/elasticsearch 可以在類，包或 級別授予權限。 例如： grant { permission org.elasticsearch.script.ClassPermission "java.util.Base64"; // allow class permission org.elasticsearch.script.ClassPermission "java.util.*"; // allow package permission org.elasticsearch.script.ClassPermission "*"; // allow all (disables filtering basically) }; 以下是如何啟用groovy.time.TimeCategory類的示例： grant { permission org.elasticsearch.script.ClassPermission "java.lang.Class"; permission org.elasticsearch.script.ClassPermission "groovy.time.TimeCategory"; }; 在向白名單添加class之前，請考慮它對Elasticsearch的安全影響。 你真的需要一個額外的類，或者你的代碼可以以更安全的方式重寫？ 我們很可能沒有將一般的有用和安全的class列入白名單。 如果你有一個你認為應該被列入白名單的class，請在GitHub上打開一個問題，我們將考慮這樣做的影響。