gatsby plugin meilisearch
v0.3.1 ?
一個基於 graphQL 查詢將 Gatsby 內容索引到 Meilsearch 的插件
若要了解 Meilisearch 及其工作原理，請參閱 Meilsearch 的文檔。
要了解 Gatsby 及其工作原理，請參閱 Gatsby 的文檔。
使用美麗搜尋雲，告別伺服器部署和手動更新。開始 14 天免費試用！無需信用卡。
在您的 Gatsby 應用程式中，添加包：
使用npm ：
npm install gatsby-plugin-meilisearch用yarn ：
yarn add gatsby-plugin-meilisearch有許多簡單的方法可以下載和執行Meilisearch實例。
例如，如果您使用 Docker：
docker pull getmeili/meilisearch:latest # Fetch the latest version of Meilisearch image from Docker Hub
docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest meilisearch --master-key=masterKey使用此指令，您的Meilisearch實例host為http://localhost:7700 ，您的主金鑰為masterKey
如果您沒有正在執行的 Gatsby，您可以啟動 [此專案中存在的 Playground](./playground/README.md) 或建立 Gatsby 專案。
如果您的應用程式尚未運行，請運行它：
gatsby develop現在您的 Gatsby 應用程式正在運行，您可以訪問以下 URL：
http://localhost:8000/ Web 應用程式的 URL。http://localhost:8000/___graphql ：GraphiQL 工具的 URL，您可以在 Playground 上建立 graphQL 查詢並要求它們。 現在您應該有一個正在運行的 Gatsby 應用程序，並且安裝了gatsby-plugin-meilisearch和一個正在運行的 Meilisearch 實例。
讓我們配置我們的插件以使其工作！在此範例中，我們將取得 Gatsby 網站每個頁面的 URL，並將它們索引到 Meilsearch。
若要讓外掛程式正常運作，請開啟位於 Gatsby 專案根目錄的gatsby-config.js設定檔。所有配置都發生在該文件中。
首先，您需要新增您的 Meilesearch 憑證。
憑證由以下部分組成：
host ：正在執行的 Meilsearch 實例的 url。api_key ： master金鑰或具有在美麗搜尋中新增文件權限的其他key 。有關權限和 API 金鑰的更多信息，請參見此處。search以外權限的金鑰。對於搜索，請使用key路由上可用的Default Search Key金鑰，或建立僅具有搜尋權限的自訂 API 金鑰。
以下列方式在gatsby-config.js檔案中新增憑證：
{
plugins : [
{
resolve : 'gatsby-plugin-meilisearch' ,
options : {
host : 'http://localhost:7700' ,
apiKey : 'masterKey' ,
} ,
} ,
]
}如果您不知道自己的憑證是什麼，請參閱本部分。
下一步是定義我們要在美麗搜尋中添加哪些資料以及如何添加。這發生在indexes字段中。
indexes欄位是一個數組，可以由多個索引物件組成。每個索引物件包含以下資訊：
indexUid ：新增資料的索引的名稱。
讓我們將索引 uid 定義為pages_url 。在建置時， pages_url索引是在Meilisearch 內部建立的。
indexUid: ' pages_url '如果pages_url已經存在，它將被刪除並在建置時重新創建
query ：GraphQL 查詢取得要加入到 Meilsearch 中的數據
讓我們提供 graphQL 查詢來檢索應用程式頁面的 URL。
query : `
query MyQuery {
allSitePage {
nodes {
path
}
}
}
` ,執行此查詢後，我們收到一個包含以下內容的data物件：
{
data : {
allSitePage : {
nodes : [
{
path : '/404/'
} ,
{
path : '/404.html'
} ,
{
path : '/'
}
]
}
}
} transformer ：將獲取的資料轉換為與美麗搜尋相容的格式。
現在我們已經透過query欄位獲取了數據，但還沒有準備好發送到Meilisearch。
使用transformer函數，我們可以將獲取的資料轉換為相容的格式。
取得資料的第一個問題是傳送到Meilisearch的文件是嵌套的，而它們應該位於陣列的根部。所以nodes的內容應該位於根。
{
data : {
allSitePages : {
nodes : [
{
'path' : '/404/'
} ,
]
}
}
}應該變成：
[
{
'path' : '/404/'
} ,
{
'path' : '/'
} ,
]第二個問題是美麗搜尋中的每個文件都需要一個唯一的標識符，稱為主鍵。
因此，每個文檔都需要一個名為id的唯一欄位。例如：
{
'id' : 1
'path' : '/404/'
} ,為此，我們需要使用轉換器方法來建立最終相容的物件陣列：
{
transformer : data =>
data . allSitePage . nodes . map ( ( node , index ) => ( {
id : index ,
... node ,
} ) ) ,
}在此函數中，我們映射data.allSitePage.nodes以傳回可由 Meilsearch 索引的物件數組。我們添加一個id字段，因為 Meilsearch 需要它來進行索引。由於這裡沒有任何可用作id字段，因此我們使用數組中當前元素的索引。
如果您想了解有關這些選項（ indexUid 、 query和transformer ）的更多信息，請參閱索引選項
填寫這些欄位後，您的 Meilisearch 配置應如下所示：
plugins: [
{
resolve : 'gatsby-plugin-meilisearch' ,
options : {
host : 'http://localhost:7700' ,
apiKey : 'masterKey' ,
indexes : [
{
indexUid : 'pages_url' ,
transformer : ( data ) =>
data . allSitePage . nodes . map ( ( node , index ) => ( {
id : index ,
... node ,
} ) ) ,
query : `
query MyQuery {
allSitePage {
nodes {
path
}
}
}
` ,
} ,
] ,
} ,
} ,
] ;gatsby-plugin-meilisearch會取得您的資料並將其新增至 Gatsby 建置上的 Meilisearch。
gatsby build建置完成後，終端機中會顯示一則訊息，確認您的內容已成功編入索引：
success gatsby-plugin-meilisearch - x.xxxs - Documents added to Meilisearch如果您需要工具在您的應用程式上整合搜尋體驗，我們的工具可以幫助您：
在 gatsby-config.js 檔案中，Meilisearch 外掛程式接受以下選項：
host （必填） host欄位是您的Meilisearch實例運行的位址。 gatsby-plugin-meilisearch需要它才能與您的 Meilisearch 實例通訊並向其發送資料。
apiKey （可選）如果 Meilsearch 實例受密碼保護，則apiKey欄位包含 API 金鑰。
skipIndexing （可選）此選項可讓您建立網站而無需索引到 Meilsearch。預設為 false
batchSize （可選）每批應包含的文件數量。預設為 1000
settings （可選）如果您想將設定傳遞到您的Meilisearch實例，您可以在此處進行。了解有關美麗搜索設置的更多信息
indexes （必填） indexes欄位是一個物件數組，每個物件代表如何將資料新增至特定索引
indexes中可以有一個或多個index對象，如果您想在不同索引中索引不同內容（或將多個不同資料索引到同一索引），這會很有用。
每個index物件應包含以下欄位：
indexUid （必填）
這是您的 Meilsearch 索引的名稱。這是必填字段，因為檢索到的資料將添加到 Meilsearch 中。例如，如果您的indexUid是pages_url ，您的內容將被索引到Meilisearch的pages_url索引中。如果您提供的索引名稱已存在，則該索引將被刪除並重新建立。
例子：
indexUid: ' pages_url '您可以在我們的文件中了解有關索引的更多資訊。
query （必填）
這是為了檢索資料而執行的 graphQL 查詢。根據您使用的插件，您的查詢可能非常具體。如果您不確定您的查詢，您可以使用 Gatsby 在開發模式下提供的 GraphiQL 工具（http://localhost:8000/___graphql）來協助您建置它。
例子：
query: `
query MyQuery {
allSitePage {
nodes {
path
}
}
}
` ,您也可以檢查我們的 Playground 的設定文件，以取得使用gatsby-plugin-mdx插件的 graphQL 查詢範例。
transformer （必需）
這是一個在將獲取的資料傳送到Meilisearch 之前對其進行轉換的函數。
執行 graphQL 查詢後，會收到一個資料對象，其結構可能會因專案而異，具體取決於您提供的查詢。由於Meilisearch需要在每個文件的根部有一個唯一的標識符，並且它應該避免嵌套對象，因此您需要相應地轉換您的資料對象。 transformer函數是執行此操作的正確位置。
例子：
transformer : data =>
data . allSitePage . nodes . map ( ( node , index ) => ( {
id : index ,
... node ,
} ) ) ,如果不使用transformer函數，數據將如下所示：
{
data : {
allSitePage : {
nodes : [
{
path : '/404/'
} ,
{
path : '/404.html'
} ,
{
path : '/'
}
]
}
}
}如上例所示使用transformer函數後，資料將如下所示，並準備好進行索引：
[
{
id : 0 ,
path : '/404/' ,
} ,
{
id : 1 ,
path : '/404.html' ,
} ,
{
id : 2 ,
path : '/' ,
} ,
] ;如果您想了解更多關於Meilisearch的文件結構，您可以在我們的文件中進行。
完整用法範例：
{
resolve : 'gatsby-plugin-meilisearch' ,
options : {
host : 'http://localhost:7700' ,
apiKey : 'masterKey' ,
skipIndexing : false ,
batchSize : 1000 ,
options : {
settings : {
searchableAttributes : [ "*" ] ,
} ,
} ,
indexes : [
{
indexUid : 'my_index' ,
transformer : ( ) => { } ,
query : ``
} ,
] ,
} 支援的 Gatsby 版本：
（此插件可能適用於較舊的 Gatsby 版本，但目前尚未測試或正式支援。）
支援的美麗搜尋版本：
該軟體包保證與Meilisearch v1.x版本相容，但某些功能可能不存在。請檢查問題以獲取更多資訊。
節點/NPM 版本：
我們建議始終使用最新版本的 Gatsby 來啟動您的新專案。
我們非常歡迎任何新的貢獻加入這個專案！
如果您想了解更多有關開發工作流程或想要做出貢獻，請造訪我們的貢獻指南以取得詳細說明！
