【PHP程式設計+MySQL資料庫+PHPMaker整合教學+技術諮詢】 本月特價優惠中! 動態的架站程式時代,要自訂PHP程式頁面有那麼難嗎? MySQL『資料庫』與『資料表』,用PHP程式有那麼難控制嗎? 你不用死背『PHP程式』與『MySQL資料庫』語法也能獨自設計完成! 這是自動化軟體程式的年代 (用PHPMaker 設計在彈指之間就能自動生成整個 PHP 程式系統) 這不是:神話!程式軟體模組取代了這一切複雜的工程。 你可以自己建構自己專屬的: 訂購表單、會員名單、擴增購物車特殊頁面 →POS 系統、CRM 系統、ERP 系統、HRM 系統...等等 (更可以加入數據資源銷售賺錢!) 該是:【見證奇蹟】的時候了! 非親眼所見....真的無法相信此神兵利器!

PHPMaker 支援 REST API,使您能夠執行 CRUD (建立、讀取、更新和刪除)生成的 Web 應用程式中的表。 您可以向 API 發出請求(例如通過 JavaScript 代碼),取得 JSON(JavaScript 物件表示法)形式的響應, 按照您的喜好解釋並呈現結果。 API請求的預設路徑是生成的應用程式下的“api”(即<mysite>/api)。

注意 在本文中,我們假設 API 位於 <mysite>/api ,因此 API 的 URL 為 /api/ ,如果您將 API 變更為其他資料夾,則需要相應變更以下示例中的 URL。

 

API 操作

REST API 是在每個選取生成的表支援的清單、檢視、加入、編輯和刪除頁面的基礎上實現的。 支援的基本 API 操作有 加入 (建立)、 清單 / 檢視 (讀取)、 編輯 (更新)、 刪除 (刪除)、 登入 (驗證使用者,如果啟用了安全性)和 檔案 (取得檔案內容)。

從 PHPMaker 2023 開始, 匯出 還支援 API 操作。 您可以將表或報告匯出到檔案,並在以後使用 匯出 API 進行檢索。

以下示例顯示了與 API 的標準訊息交換 (使用demo資料庫的“cars”表進行演示):

 

示例 1 – 通過鍵取得記錄(檢視操作)

$("#input-id").change(function() { // Assume "input-id" is an input for key value
    let object = "<Table>", // Replace <Table> by actual table name
        key = encodeURIComponent($(this).val());
    $.get("/api/view/" + object + "/" + key, function (res) { // Get response from View page API
        if (res && res.success) {
            let row = res[object];
            alert(JSON.stringify(row)); // Show output JSON
        } else {
            alert(res.failureMessage);
        }
    });
});
JavaScript

HTTP請求
取得 /api/view/cars/1
接受:應用程式/json

HTTP響應
200 好

{
    "success": true,
    "version": "19.0.0",
    "cars": {
        "ID": 1,
        "Trademark": 1,
        ...
    }
}
JSON

 

示例 2 – 建立記錄(加入操作)

$("#btn-id").click(function() {//  Assume "btn-id" is the submit button for the add form
    let object = "<Table>", // Replace <Table> by actual table name
        data = $(this.form).serialize();
    $.post("/api/add/" + object, data, function (res) { // Get response from Add page API
        if (res && res.success) {
            let row = res[object];
            alert(JSON.stringify(row)); // Show output JSON
        } else {
            alert(res.failureMessage);
        }
    });
});
JavaScript

HTTP請求
POST /api/ 加入/汽車
商標=1&…
接受:應用程式/json

如果您的資料是 JSON,則 HTTP 請求應為:

POST /api/ 加入/汽車
{“商標”:1,…}
內容類型:application/json
接受:應用程式/json

注意 如果您的資料是 JSON,請確保已將內容類型設定為 application/json 並確保使用 完整的 JSON 語法 可以正確解析它 ,以便json_decode

HTTP 響應(成功)
200 好

{
    "success": true,
    "version": "19.0.0",
    "cars": {
        "ID": 16,
        "Trademark": 1,
        ...
    }
}
JSON

HTTP 響應(失敗)
200 好

{
    "success": false,
    "version": "19.0.0",
    "failureMessage": "<reason>"
}
JSON

 

示例 3 – 匯出和檢索匯出的檔案(匯出操作)

1.匯出檔案並取得檔案ID

let object = "<Table>", // Replace <Table> by actual table name
    exportType = "<ExportType>"; // Replace <ExportType> by actual export type (e.g. excel/word/pdf)
  // Get response from Export API (Replace <FileName> by expected file name, if any)
$.get("/api/export/" + exportType + "/" + object + "?filename=<FileName>&save=1", function (res) {
    if (res && res.success) {
        alert(res.fileId); // Get exported file ID
    } else {
        alert(res.failureMessage);
    }
});
JavaScript

HTTP請求
GET /api/export/excel/cars?filename=…&save=1&output=0
接受:應用程式/json

HTTP響應
200 好

{
  "success": true,
  "version": "19.0.0",
  "fileid": "575879b9-9c87-45de-9403-8c7e753981e5"
}
JSON

2.通過檔案ID檢索匯出的檔案內容

let fileId = "<FileId>"; // File Id from previous export action response
$.get("/api/export/" + fileId, function (res) { // Get file content from Export API
      // Output file content
});
JavaScript

HTTP請求
取得 /api/export/575879b9-9c87-45de-9403-8c7e753981e5

HTTP響應
200 好

返回匯出的檔案內容。

 

支援的 API 操作

備註 如果您啟用 “使用 Swagger UI for API” (請參閱​​“工具”-> “進階設定” ),則可以使用 Swagger UI 位於 http://mysite/basepath/swagger/ 的 測試這些操作。

POST /api/登入 取得 /api/登入

POST /api/登入 如果使用者從外部使用者端(不在生成的 Web 應用程式內)使用 REST API,則使用者需要首先登入。 登入 API 通過 JWT 令牌對使用者進行身份驗證, 使用 JWT 對使用者進行身份驗證。 有關詳細訊息,請參閱下面

/api/登入
使用者名=admin&密碼=master

參數

使用者名 (表單資料)
使用者名。 必需的。
密碼 (表單資料)
密碼。 必需的。
安全碼 (表單資料)
谷歌身份驗證器安全代碼。 如果 兩因素身份驗證,則為必需。 啟用了
過期 (表單資料)

JWT 令牌的過期時間(小時)。 選修的。

登入後API過期時間的預設值 (秒) 。 如果不指定,則使用

權限 (表單資料)

結合使用 與expire 。 選修的。如果指定,則 JWT 僅對指定權限有效。 請參閱下表,其中列出了權限類型和值。

請注意, 該權限只能是登入使用者權限的子集。

取得 /api/登入

如果 啟用了進階設定 “容許通過 URL 登入” ,則接受,例如

/api/login?使用者名=admin&密碼=master

參數

使用者名 (查詢)
使用者名。 必需的。
密碼 (查詢)
密碼。 必需的。
安全碼 (查詢)
谷歌身份驗證器安全代碼。 如果 兩因素身份驗證,則為必需。 啟用了
過期 (查詢)

JWT 令牌的過期時間(小時)。 選修的。

登入後API過期時間的預設值 (秒) 。 如果不指定,則使用

權限 (查詢)

結合使用 與expire 。 選修的。如果指定,則 JWT 僅對指定權限有效。 請參閱下表,其中列出了權限類型和值。

請注意, 該權限只能是登入使用者權限的子集。

權限類型和值 下面列出了權限類型和值的清單。 要指定權限類型的組合,請將值相加。 例如,對於“清單 + 匯出”,請使用 8 + 1024(即 1032)

類型
價值
加入
1
刪除
2
編輯
4
清單
8
行政
16
看法
32
搜尋
64
匯入
128
抬頭
256
512
匯出
1024

成功回復

{
"JWT": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9......"
}
JSON
說明 在Swagger UI中測試時,登入後需要點擊 授權 按鈕並輸入“Bearer <JsonWebToken>”對自己進行授權,然後才能測試其他操作。

響應失敗
401 未經授權

取得 /api/list/{表}

取得記錄清單,例如

/api/清單/汽車

參數

(路徑)
表名。 必需的。
開始 (查詢)
起始記錄號。 可選,預設 = 1。
記錄頁面 (查詢)
每頁記錄。 可選,預設 = 每頁記錄數 設定,需要啟動 可選頁面大小 設定。
訂單 (查詢)
欄位名稱。 可選,按指定欄位排序,需要啟動 清一頁面中的排序 設定。
訂單類型 (查詢)
按升冪 (‘ASC’) 或降冪 (‘DESC’) 排序。 可選,需要啟動 清一頁面中的排序 設定。
<欄位名稱> (查詢)
按值搜尋指定欄位。 可選,需要啟動 進階/擴展搜尋設定。 清一頁面中的

成功回復

{
  "success": true,
  "version": "19.0.0",
  "cars": [
      {
          "ID": 1,
            "Trademark": 1,
            ...
      },
      {
          "ID": 2,
            "Trademark": 1,
            ...
      }
  ]
}
JSON

響應失敗

{
  "success": false,
  "version": "19.0.0",
  "failureMessage": "<reason>"
}
JSON
GET /api/export/{類型}/{表}
取得 /api/export/{id}
GET /api/匯出/搜尋

GET /api/export/{類型}/{表} 從表中匯出記錄,例如

/api/export/excel/汽車

參數

類型 (路徑)
匯出類型,例如“excel”、“word”、“pdf”、“html”。 必需的。
(路徑)
表名。 必需的。
(查詢)
記錄的主鍵。 可選,用於檢索單個記錄(從“檢視”頁面)。
頁面 (查詢)
頁碼。 選修的。
記錄頁面 (查詢)
每頁記錄數。 選修的。
檔名 (查詢)
匯出檔案的檔名。 可選,僅用於覆蓋預設檔名。
儲存 (查詢)
將匯出的檔案儲存在伺服器上。 值:0 或 1。可選,預設為 0。
輸出 (查詢)
將匯出的檔案輸出到伺服器上。 值:0或1。可選,預設為1,即直接輸出檔案。

成功回復
匯出時輸出=0:

{
  "success": true,
  "version": "19.0.0",
  "fileId": "575879b9-9c87-45de-9403-8c7e753981e5"
}
JSON

不帶“儲存”參數匯出,或輸出=1:
<匯出的檔案內容>

響應失敗
檢視失敗響應清單

取得 /api/export/{id}

從id取得匯出的檔案,例如

/api/export/575879b9-9c87-45de-9403-8c7e753981e5

參數

id (路徑)
匯出檔案的檔案 ID。 必需的。
檔名 (查詢)
匯出檔案的檔名。 可選,僅用於覆蓋預設檔名。

成功回復

<匯出的檔案內容>

響應失敗
檢視失敗響應清單

GET /api/匯出/搜尋

搜尋匯出的檔案,例如

/api/export/search/?limit=1

參數

限制 (查詢)
最新匯出檔案數(整數)
類型 (查詢)
匯出類型,例如“excel”、“word”、“pdf”、“html”
表名 (查詢)
表名
檔名 (查詢)
檔名
日期時間 (查詢)
約會時間
輸出 (查詢)
將匯出的檔案輸出到伺服器上。 值:0或1。可選,預設為1,即直接輸出檔案。

成功回復
搜尋輸出=0:

{
  "success": true,
  "version": "19.0.0",
  "fileId": [ "575879b9-9c87-45de-9403-8c7e753981e5" ]
}
JSON

不使用“output”參數或output=1 進行搜尋:
<匯出的檔案內容>

注意: 如果搜尋後有多個檔案,則輸出將為匯出檔案的壓縮檔。

響應失敗
檢視失敗響應清單

GET /api/view/{表}/{鍵}

通過key取得單條記錄,例如

/api/檢視/汽車/1

參數

(路徑)
表名。 必需的。
(路徑)
記錄的主鍵。 必需的。

成功回復

{
"success": true,
"version": "19.0.0",
"cars": {
    "ID": 1,
        "Trademark": 1,
        ...
    }
}
JSON
響應失敗
檢視失敗響應清單
POST /api/add/{表}

插入一條新記錄,例如

/api/加入/汽車
商標=1&…

參數

(路徑)
表名。 必需的。
<欄位名稱> (表單資料)
要插入的欄位值。 必需的。

成功回復

{
  "success": true,
  "version": "19.0.0",
  "cars": {
      "ID": 16,
      "Trademark": 1,
      ...
  }
}
JSON
響應失敗
檢視失敗響應清單
POST /api/註冊

在使用者表中註冊一個新使用者,例如

/api/註冊
使用者名=新使用者&…

參數

<欄位名稱> (表單資料)
要插入的欄位值。 必需的。

成功回復

{
  "success": true,
  "version": "19.0.0",
  "employees": {
      "EmployeeID": 10,
      "Username": "newuser",
      ...
  }
}
JSON
響應失敗
檢視失敗響應清單
POST /api/edit/{表}/{鍵}

通過鍵更新現有記錄,例如。

/api/編輯/汽車/1
商標=2&…

參數

(路徑)
表名。 必需的。
(路徑)
記錄的主鍵。 必需的。
<欄位名稱> (表單資料)
要更新的欄位值。 必需的。

成功回復

{
  "success": true,
  "version": "19.0.0",
  "cars": {
      "Trademark": 2,
      ...
  }
}
JSON
Failed response
See failed response for list

GET /api/delete/{table}/{key} POST /api/delete/{table}

GET /api/delete/{table}/{key} Delete an existing record by key, e.g.

/api/delete/cars/1

Parameters

table (path)
Table name. Required.
key (path)
Primary key of the record to be deleted. Required.

POST /api/delete/{table}

Delete multiple records by keys, e.g.

/api/delete/cars
key_m[]=1&key_m[]=2&…

Parameters

table (path)
Table name. Required.
key_m[] (表單資料)
要刪除的記錄的主鍵。 必需的。
注意 如果是複合鍵,則 <FieldValue> 是逗號分隔值。

成功回復

{
  "success": true,
  "version": "19.0.0",
  "cars": {
      "ID": 1,
      "Trademark": 1,
      ...
  }
}
JSON
響應失敗
檢視失敗響應清單

GET /api/file/{表}/{字段}/{鍵} GET /api/檔案/{表}/{路徑}

GET /api/file/{表}/{字段}/{鍵} 按主要模式取得檔案訊息,例如

/api/檔案/員工/照片/1

參數

(路徑)
表名。 必需的。
欄位 (路徑)
欄位名稱。 必需的。
(路徑)
記錄的主鍵。 必需的。

GET /api/檔案/{表}/{路徑}

通過加密檔案路逕取得檔案資料,例如

/api/檔案/員工/xxx

參數

(路徑)
表名。 必需的。
路徑 (路徑)
加密的檔案路徑。 必需的。
注意 如果是複合鍵,則在 Swagger UI 中測試時,輸入 {key} 作為逗號分隔值。

成功回復
對於 blob 欄位(例如 cars 表中的圖片欄位),具有正確內容類型的檔案欄位的二進位內容。
對於字串欄位(例如員工表中的照片欄位),檔案位置的 JSON 響應:

{
  "Photo": {
      "EmpID1.jpg": "http://<my_site>/upload/EmpID1.jpg"
  },
  "version": "19.0.0"
}
JSON

如果檔案路徑被加密:

{
  "Photo": {
      "EmpID1.jpg": "http://<my_site>/api/file/employees/<encrypted_file_path>"
  },
  "version": "19.0.0"
}
JSON
then you can use the second file action to get the file content.Failed response
Empty response
POST /api/upload

上傳檔案,例如

/api/upload

請參閱下面的示例。

參數

正文 (表單資料)
表格資料。 必需的。

成功回復
檔案令牌和檔案訊息的 JSON 響應:

{
  "success": true,
  "version": "19.0.0",
  "token": "<FileToken>",
  "files": [
      ...file info...
  ]
}
JSON

響應失敗

{
  "success": false,
  "version": "19.0.0",
  "files": []
}
JSON

GET /api/permissions/{userLevelID} POST /api/permissions/{userLevelID}

GET /api/permissions/{userLevelID} 取得權限,例如

/api/權限/1

參數

使用者層級ID (路徑)
使用者層級 ID。 必需的。

POST /api/permissions/{userLevelID}

更新權限,例如

/api/權限/1
{“汽車”:264,…}

參數

使用者層級ID (路徑)
使用者層級 ID。 必需的。
身體 (身體)
JSON 格式的權限,例如 { “<Table1>”: <Permission1>, “<Table2>”: <Permission2>, … } 。 必需的。 請參閱上面登入 API 中的權限類型和值清單。

Successful response
Get permissions:

{
  "userlevel": 1,
  "permissions": {
      "cars": 8,
      ...
  }
}
JSON

Update permission:

{
  "success": true,
  "userlevel": 1,
  "permissions": {
      "cars": 264,
      ...
  }
}
JSON

響應失敗

{
  "success": false,
  "userlevel": 1
}
JSON

 

使用 JWT(JSON Web 令牌)對使用者進行身份驗證

REST API 是無狀態的。 每個API請求相互獨立,伺服器中不存儲任何會話資料 記錄 API 請求的現用的狀態。 要從 API 訪問受保護的資源, 操作取得 JSON Web 令牌 (JWT) 來對使用者進行身份驗證 您需要首先使用登入 , 然後在後續 API 請求中將 JWT 作為身份驗證標頭傳遞。

筆記

  1. 如果您在訪問受保護資源時不提供 JWT,您將收到 401 Unauthorized 響應。
  2. 每個 JWT 都有一個有限的時間跨度,因此您可以 令牌過期後需要重新對使用者進行身份驗證。

要了解有關 JWT 的更多訊息,請訪問 https://jwt.io/introduction/

以下 JavaScript 展示瞭如何通過 JWT 從 API 取得受保護的資源。 首先對使用者進行身份驗證 點選 登入 按鈕。 然後點擊 取得訂單記錄 按鈕即可取得訂單記錄 這是受保護的資源。

$(function() {
    let store = store || {};
    // Store JWT
    store.setJWT = function (data) {
        this.JWT = data;
    }
    // Login
    $("#frm-login").submit(function (e) {
        e.preventDefault();
        let data = $("#frm-login").serialize();
        $.post("/api/login", data, function (data) {
            $("button").removeAttr("disabled");
            store.setJWT(data.JWT);
        }).fail(function (xhr, status, error) {
            alert("login failed. status: " + status + ", error: " + error);
        });
    });
    // Get protected resource
    let getProtectedResource = function (e) {
        e.preventDefault();
        $.ajax({
            url: "/api/view/orders/10248",
            type: "GET",
            success: function (data, status, xhr) {
                let out = (data && typeof data === 'object') ? JSON.stringify(data) : data;
                alert(out);
            },
            error: function (xhr, ajaxOptions, thrownError) {
                alert("status: " + xhr.status + ", error: " + thrownError);
            },
            beforeSend: function (request) { // Set JWT header
                request.setRequestHeader('X-Authorization', 'Bearer ' + store.JWT);
            }
        });
    }
    $("#btn-with-token").click(getProtectedResource);
});
JavaScript
<form id="frm-login" method="post">
    <input type="text" name="username" value="admin">
    <input type="text" name="password" value="master">
    <input type="submit" value="Login">
</form>
<button id="btn-with-token" type="button" disabled>Get order record</button>
超文字標示語系

 

 

上傳檔案

要上傳檔案,您可以使用 上傳 操作(見上文)。 您可以通過 HTML 5 上傳檔案,例如

<input type="file" id="id" name="name" onchange="uploadFiles(this);">
超文字標示語系

如果你想讓使用者選取多個檔案,只需 使用multiple 在 input 元素上 加入[]即可: 屬性並在名稱中

<input type="file" id="id" name="name[]" multiple onchange="uploadFiles(this);">
超文字標示語系
// Upload files
function uploadFiles(el) {
    let files = el.files, // Get FileList object
        name = el.name,
        url = "/api/upload",
        xhr = new XMLHttpRequest(),
        fd = new FormData();
    xhr.responseType = "json";
    xhr.open("POST", url, true);
    xhr.onreadystatechange = function() {
        if (xhr.readyState == 4 && xhr.status == 200 && xhr.response) { // Files uploaded
            if (xhr.response.filetoken) // Check file token
                console.log(xhr.response.filetoken);
        }
    };
    Array.from(files).forEach(file => fd.append(name, file)); // Append File object to form data
    xhr.send(fd);
}
JavaScript

筆記

  1. 當使用者選取檔案時, files 輸入元素的 屬性是一個FileList 物件,其中內含 File物件。 表示使用者選取的檔案的
  2. 如果檔案上傳成功,您將獲得帶有檔案令牌的成功響應(見上文),然後您可以使用檔案令牌作為欄位的欄位值來進行加入 編輯 操作
  3. 不支援將多個檔案上傳到 BLOB 欄位。

 

 

建立您自己的 API 操作

除了內建 API 操作之外,您還可以通過 Api_Action 伺服器事件加入自己的 API 操作(請參閱 伺服器事件和使用者端腳本 )。

示例 1 – 你好世界

function Api_Action($app)
{
    $app->get('/hello/{name}', function ($request, $response, $args) {
        $name = $args["name"] ?? null; // Get the input value
        if ($name !== null) {
            $response = $response->write("Hello, " . $name); // Write to response
        }
        return $response; // Return Psr\Http\Message\ResponseInterface object
    });
}
PHP

使用者現在可以訪問 URL /api/hello/John 來取得響應文字 “你好約翰”。

筆記

  1. 返回 Psr\Http\Message\ResponseInterface物件。 確保在路由回呼中
  2. 參數的詳細訊息,請參閱 請求 響應 有關 回呼函數的$request $response 物件。

 

示例 2 – 按名稱取得產品

function Api_Action($app)
{
    $app->get('/getProductByName/{name}', function ($request, $response, $args) {
        $name = $args["name"] ?? null; // Get the input value
        if ($name !== null) {
            $response = $response->withJson(ExecuteRow("SELECT * FROM products WHERE ProductName = '" . AdjustSql($name) . "'")); // Select the record by name and return as JSON
        }
        return $response; // Return Psr\Http\Message\ResponseInterface object
    });
}
PHP

現在可以使用以下 JavaScript 訪問產品資料:

$.get("/api/getProductByName/Chai", function (res) {
    console.log(res); // Show the result in console
});
JavaScript
注意 參閱 返回 JSON 有關從回呼函數返回 JSON 資料的更多詳細訊息,請 。

 

進階設定

中自訂 REST API 的以下設定 您可以在進階設定

API JWT 簽名密鑰
用於簽署 JSON Web 令牌 (JWT) 的密鑰。 非可選,請確保使用不同的值 不同的項目並將其儲存在秘密的地方
API JWT 簽名算法
用於簽署 JWT 的算法。 預設為 HS512 。 有關更多可能的值,請參閱 JWT 網站: https://jwt.io/introduction
API JWT 授權標頭
存儲 JWT 的標頭名稱。 預設值為 X 授權
登入後API訪問時間(秒)
登入後可以訪問受保護資源的時間。 預設值為 0 。 如果你想延遲訪問,可以將其變更為10。
登入後API過期時間(秒)
JWT 過期時間。 預設值為 3600(60 分鐘)。 一旦 JWT 過期,使用者將需要再次進行身份驗證。
API 自訂標頭

如果啟用,則 IIS/Apache 將發出 Access-Control-Allow-Origin、Access-Control-Allow-Headers 和 Access-Control-Allow-Methods。 預設為 false。

筆記

  1. 對於 Apache, 必須啟用mod_headers 才能使此設定起作用。
  2. 如果禁用,標頭將由 CORS 中間件發出。
API 訪問控制容許來源
Access-Control-Allow-Origin 標頭。 如果未指定,預設值為“*”,以便外部應用程式可以訪問 REST API。
API 訪問控制容許標頭

Access-Control-Allow-Headers 標頭。

注意 CORS 安全清單請求標頭 始終是容許的,因此通常不會在 Access-Control-Allow-Headers 中列出(除非需要規避安全清單 附加限制 )。