OAuth2 API

校內伺服器 API

校內伺服器 API 僅限於校內伺服器使用, API 存取會檢查是否為學校的 IP 範圍,各校 IP 分配表由資網中心統一設定。

  1. 建立 API
  • 登入 CloudSchool , 進入系統管理/模組管理/API及憑證設定

    ../_images/api-1.png
  • 新增 學校伺服器 API

    ../_images/api-2.png
  1. 名稱: API 顯示名稱
  2. 類型:
    • 學校伺服器: 帳號認證、同步學籍核心資料(同步局端處室、教師、學生資料)、 校務資料 (校務模組資料,例公告欄、行事曆等資訊)
    • 校務行政: 帳號認證、校務資料 (校務模組資料,例公告欄、行事曆等資訊)
    • 認證: 帳號認證
  3. 限用伺服器 IP 位址 (選填): 限定伺服器IP,如未設定,以學校網段為範圍。
  4. 已授權的重新導向 URI (選填): 適用web認證,重新導向 URI 用於網路伺服器發出的要求。 使用者透過 『CloudSchool 校務系統』 進行驗證後, 系統就會將他們重新導向至應用程式中的這個路徑。此路徑會附帶存取的授權碼。
  1. 測試 API
  • 將 用戶端ID (client ID) 和 用戶端密碼(client secret) 複製到測試工具或範例程式

    ../_images/api-5.png
  • 測試工具

    Rest API 的測試工具很多,可選擇自己常用的工具測試,以 RESTer 為例

    1. chrome 安裝 : https://chrome.google.com/webstore/detail/rester/eejfoncpjfgmeleakejdcanedmefagga
    2. firefox 安裝 : https://addons.mozilla.org/zh-TW/firefox/addon/rester/
  • 測試方式,以 學期資料 api 為例 https://api.tc.edu.tw/semester-data

    設定 AUTHORIZATION

    ../_images/api-6.png
    1. 設定 api url , method 為 GET url 填入 https://api.tc.edu.tw/semester-data
    2. 選擇 AUTHORIZATION,設定認證
    3. 第一次設定,選擇 Create new configuration ,設定 OAuth2

    設定 OAuth2

    ../_images/api-7.png
    1. OAuth title 可自行命名
    2. OAuth2 Flow 選擇 Client Credentials
    3. Access Token Request: Method ,選擇 POST
    4. Access Token Request Endpoint ,鍵入 https://api.tc.edu.tw/oauth?authorize
    5. Access Token Request Client Authentication ,選擇 HTTP Basic authentication
    6. Client ID ,鍵入 學校伺服器 API Client ID
    7. Client Secret ,鍵入 學校伺服器 API Client Secret
    8. scope 免填

    取得 token

    ../_images/api-8.png
    1. 按下按鈕,向 AUTHORIZATION Server 取 token
    2. token 值,存活 30分鐘

    執行 API

    ../_images/api-9.png
    1. 回到 HEADER
    2. 新增 Content-Type 為 application/json
    3. 剛取到的 token 值,會顯示在這裡 。
    4. 按下 send 執行
    ../_images/api-10-1.png
    1. Response 200 OK, 表示成功,如 token 過期,會出現 401 Unauthorized 錯誤,重新取 token
    2. server 回應的 http 表頭
    3. 取出的資料,為 json 格式
  1. 範例程式

OAuthApiTest.php

<?php
/**
  同步遠端學校學期資料
**/

// 更改為學校的 API ID
$client_id = 'XXXXXXXXXXXXXXXXXXXXX';
// 更改為學校的 API 密碼
$client_secret = 'XXXXXXXXXXXXXXXXX';

// =================================================

// API NAME
$api_name = '/semester-data';

// API URL
$api_url = 'https://api.tc.edu.tw';


// 建立 CURL 連線
$ch = curl_init();

// 取 access token
curl_setopt($ch, CURLOPT_URL, $api_url."/oauth?authorize");

// 設定擷取的URL網址
curl_setopt($ch, CURLOPT_POST, TRUE);

// the variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);


curl_setopt($ch, CURLOPT_POSTFIELDS, array(
'client_id' => $client_id,
'client_secret' => $client_secret,
'grant_type' => 'client_credentials'
));

$data = curl_exec($ch);
$data = json_decode($data);

$access_token = $data->access_token;

$authorization = "Authorization: Bearer ".$access_token;



curl_setopt($ch, CURLOPT_URL, $api_url.$api_name);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json' , $authorization )); // **Inject Token into Header**
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

//curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$result = curl_exec($ch);

$data = json_decode($result);

print_r($data);

校端 API 列表

  1. 同步學期資料

    項目 說明
    URL https://api.tc.edu.tw/semester-data
    HTTP Method GET
    Content-Type application/json
    AUTHORIZATION OAuth2
    回傳資料格式 json
    學期資料 schema 學期資料定義.json
  2. 更改師生密碼

    項目 說明
    URL https://api.tc.edu.tw/change-password
    HTTP Method PATCH
    Content-Type application/json
    AUTHORIZATION OAuth2
    回傳資料格式 json
    schema 更改師生密碼上傳定義.json
    參考
    ../_images/api-11.png
  3. 校務佈告欄

    項目 說明
    URL https://api.tc.edu.tw/school-news
    HTTP Method POST
    Content-Type application/json
    AUTHORIZATION OAuth2
    回傳資料格式 json
    schema 佈告欄上傳定義.json

    URL Query

    參數 說明
    open_new_kind_id 查詢處室,例 https://api.tc.edu.tw/school-news?open_new_kind_id=1
    query_string 查詢字串,例 https://api.tc.edu.tw/school-news?query_strung=教師
    page 頁數,例 https://api.tc.edu.tw/school-news?page=2

    ** 上列參數可以合併使用

    參考
    ../_images/api-12.png
  4. 學生榮譽榜

    項目 說明
    URL https://api.tc.edu.tw/honor
    HTTP Method POST
    Content-Type application/json
    AUTHORIZATION OAuth2
    回傳資料格式 json
    schema 學生榮譽榜上傳定義.json

    URL Query

    參數 說明
    level 查詢榮譽類別,例 https://api.tc.edu.tw/honor?level=學習表現
    page_size 每頁筆數,例 https://api.tc.edu.tw/honor?level=學習表現&page_size=5
    page 頁數,例 https://api.tc.edu.tw/honor?level=學習表現&page_size=5&page=2

    ** 上列參數可以合併使用

    參考
    ../_images/api-13.png