這篇教學會帶你走完一支 mashup 的誕生過程:頁面由多個資料來源拼裝而成,而其中一個區塊要抓的資料,恰好來自填充另一個區塊的那個來源。這就是 mashup 的核心——資料聚合。Ajax 在此扮演關鍵角色,因為它讓頁面的某個區塊能在不刷新整頁的情況下更新。
示範的組合是 Google Maps API 加 Flickr API:在 Google 地圖上點一下,Map API 回傳該位置的經緯度,這組座標透過 Ajax 送到 Flickr,Flickr 再回傳在該座標附近被地理標記的照片。
過程中還會用到 Flickr 的另一項特性:標籤。標籤是描述照片的關鍵字,例如一張金門大橋的照片可能被標上 San Francisco、bridge、Golden Gate、fog。這些標籤由upload照片的人自己加上,所以我們在這裡不是建立標籤,而是拿它來搜尋。
本教學的順序如下:先建立並操作 Google 地圖,接著回顧 Ajax 的基本呼叫方式,然後把兩者接成 mashup,最後說明 Flickr API 的取得與使用。
本教學幾乎都是 JavaScript 程式碼。Ajax 並不是一種語言,而是一套高度依賴 JavaScript 的程式設計典範,因此具備 JavaScript 的實作經驗是基本要求,對 Ajax 有概念更好。你也需要理解地圖的基本屬性:距離、座標與比例尺。
環境方面,你需要一個可存取的 Web 伺服器、一個有效網域,以及對該網域寫入檔案的權限。伺服器端使用 PHP,但程式碼很單純,多半只是查詢資料或向服務取資料,用你熟悉的語言改寫並不難。
過去我們用 Hello World 初次體驗一個語言;在 Web 2.0 的年代,人們改做地圖。
先準備一個 Google 帳號,然後申請一組 Google Maps API 金鑰(申請前請務必讀過服務條款)。Google 會給你一組專屬金鑰與一份可直接存下的範例頁,接著動手做「Hello Map」就非常容易了。
以下是 Google 提供的範例程式碼,金鑰以 X 遮去(實際金鑰是一串長的隨機字元):
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="https://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google Maps JavaScript API Example</title>
<script src="https://maps.google.com/maps?file=api&v=2&key=XXXXXXXX"
type="text/javascript"></script>
<script type="text/javascript">
//<![CDATA[
function load() {
if (GBrowserIsCompatible()) {
var map = new GMap2(document.getElementById("map"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
}
}
//]]>
</script>
</head>
<body onload="load()" onunload="GUnload()">
<div id="map" style="width: 500px; height: 300px"></div>
</body>
</html>
這段程式碼產生的地圖,預設以 Google 位於加州 Mountain View 的總部為中心。地圖可以用滑鼠拖曳,而初始位置由這一行決定:
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
圖 1 最初呈現的地圖
想在 Googletown 閒晃,圖 1 很夠用;但我們要做的事更多。要定位一個實際地點,你需要經緯度。取得方式很多——地圖集、專業軟體,或直接上網找。搜尋免費經緯度資料會出現不少好用的站台。
只要改動 load 函式裡的座標,就能顯示費城。費城的座標是 39.9531 與 -75.1651;同時把 setCenter 的第二個參數從 13 提高到 14,視野就更近一些(數值越低看得越遠,例如 4 只能看到地球的大半)。因此費城的初始設定寫成:
map.setCenter(new GLatLng(39.9531, -75.1651), 14);
圖 2 放大後的費城地圖
地圖能建、能換座標,接下來就是把地圖中心的座標送去伺服器處理——這是 Ajax 的活儿。如果你對 Ajax 的記憶已經模糊,這裡先把它撿回來。
Ajax 從建立一個 XMLHttpRequest 物件開始。由於瀏覽器相容性問題,實務上會寫成「依序嘗試」的形式,直到成功取得物件為止:
var XMLHttpRequestObject = false;
try {
XMLHttpRequestObject = new ActiveXObject("MSXML2.XMLHTTP");
} catch (exception1) {
try {
XMLHttpRequestObject = new ActiveXObject("Microsoft.XMLHTTP");
} catch (exception2) {
XMLHttpRequestObject = false;
}
}
if (!XMLHttpRequestObject && window.XMLHttpRequest) {
XMLHttpRequestObject = new XMLHttpRequest();
}
這種寫法對早期 Internet Explorer 是必要的:IE 7 採用標準的 XMLHttpRequest 物件,更早的版本則使用 Microsoft 自家的 XMLHTTP 物件。上面的程式碼能自動找出適合當前瀏覽器的那一個。下文一律稱之為 XMLHttpRequest 物件。
這段程式碼通常在頁面載入時執行,確保需要時物件已就緒。它是頁面與伺服器之間的橋樑,等於一個小型的頁面刷新機制:用來取用伺服器上的資料或觸發伺服器端的程序,必要時可一併送出參數;伺服器則透過該物件回傳狀態與資料,頁面拿到後就能使用。
資料回來之後,最常見的呈現方式是把它寫進某個 div 或其他元素的 innerHTML。以下取自本教學後段的完整範例:
function getPhotos(lat, lon) {
if (XMLHttpRequestObject) {
var obj = document.getElementById("photosgohere");
var tags = document.getElementById("tags").value;
var query = 'photos.php?lat=' + lat + '&lon=' + lon + '&tags=' + tags;
XMLHttpRequestObject.open("GET", query);
XMLHttpRequestObject.onreadystatechange = function() {
if (XMLHttpRequestObject.readyState == 4 &&
XMLHttpRequestObject.status == 200) {
obj.innerHTML = XMLHttpRequestObject.responseText;
}
}
XMLHttpRequestObject.send(null);
}
}
這是個 JavaScript 函式,必須被某個事件(例如 click 或 onchange)觸發才會執行。它的流程是:
客戶端只是一半,伺服器端的 photos.php 負責查資料並把結果寫回瀏覽器:
<?php
$lonlow = urlencode($_GET['lon'] - 0.1);
$lonhigh = urlencode($_GET['lon'] + 0.1);
$latlow = urlencode($_GET['lat'] - 0.1);
$lathigh = urlencode($_GET['lat'] + 0.1);
$tags = urlencode($_GET['tags']);
function getInfo($url) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($ch);
curl_close($ch);
return $result;
}
$url = "https://api.flickr.com/services/rest/?method=flickr.photos.search"
. "&api_key=xxxxxx&tags={$tags}"
. "&bbox={$lonlow},{$latlow},{$lonhigh},{$lathigh}"
. "&per_page=10";
$result = getInfo($url);
$content = simplexml_load_string($result);
echo 'Total Found=' . $content->photos['total'] . '<br /><br />';
foreach ($content->photos->photo as $photo) {
$title = $photo['title'];
$farmid = $photo['farm'];
$serverid = $photo['server'];
$id = $photo['id'];
$secret = $photo['secret'];
$owner = $photo['owner'];
$thumb_url = "https://farm{$farmid}.static.flickr.com/{$serverid}/{$id}_{$secret}_t.jpg";
$page_url = "https://www.flickr.com/photos/{$owner}/{$id}";
$image_html = "<a href='{$page_url}'><img alt='{$title}' src='{$thumb_url}'/></a>";
echo '<p>' . $image_html;
echo '<br />' . $title . '</p>';
}
?>
這裡大致做了三件事:把傳入的經緯度各自加減 0.1 度,擴成四個座標以定義一個地理邊界框;帶著 API 金鑰、標籤與這四個座標呼叫 Flickr API;把回傳的 XML 處理成可用的格式,用 echo 寫成一串預先組好的 HTML,最後成為 photosgohere 這個 div 的 innerHTML。
注意:呼叫 Flickr 一樣需要 API 金鑰,這裡同樣以 X 代替;取得金鑰的完整流程見後文「設定好 Flickr」。
回到清單 1 的基本 Google Map 結構。GMap2 物件建立之後,可以用 listener 為它掛上事件監聽,告訴地圖「在指定事件發生時要做什麼」。地圖本來就能拖曳,現在我們讓它也能回應點擊。
完整的客戶端 HTML 如下(HTML 與 JavaScript 都在同一支檔案裡):
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="https://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google Maps + Flickr mashup</title>
<script type="text/javascript"
src="https://maps.google.com/maps?file=api&v=2&key=xxxxx"></script>
<script type="text/javascript">
var XMLHttpRequestObject = false;
try {
XMLHttpRequestObject = new ActiveXObject("MSXML2.XMLHTTP");
} catch (exception1) {
try {
XMLHttpRequestObject = new ActiveXObject("Microsoft.XMLHTTP");
} catch (exception2) {
XMLHttpRequestObject = false;
}
}
if (!XMLHttpRequestObject && window.XMLHttpRequest) {
XMLHttpRequestObject = new XMLHttpRequest();
}
function getPhotos(lat, lon) {
if (XMLHttpRequestObject) {
var obj = document.getElementById("photosgohere");
var tags = document.getElementById("tags").value;
var query = 'photos.php?lat=' + lat + '&lon=' + lon + '&tags=' + tags;
XMLHttpRequestObject.open("GET", query);
XMLHttpRequestObject.onreadystatechange = function() {
if (XMLHttpRequestObject.readyState == 4 &&
XMLHttpRequestObject.status == 200) {
obj.innerHTML = XMLHttpRequestObject.responseText;
}
}
XMLHttpRequestObject.send(null);
}
}
function load() {
if (GBrowserIsCompatible()) {
var map = new GMap2(document.getElementById("map"));
map.setCenter(new GLatLng(39.9531, -75.1651), 14);
}
GEvent.addListener(map, "click", function() {
var coords = map.getCenter().toString();
document.getElementById("message").innerHTML = coords;
var inner = coords.substr(1, coords.length - 2);
var pos = inner.search(/,/);
var lat = inner.substring(0, pos);
var lon = inner.substring(pos + 1, inner.length);
getPhotos(lat, lon);
});
}
</script>
</head>
<body onload="load()">
<table><tr>
<td valign="top">
<div id="map" style="width: 500px; height: 450px"></div><br />
<b><div id="message"></div></b><br />
<form>
<b>Enter tag(s) here, then click on the map</b><br />
<input type="text" id="tags" />
</form>
</td>
<td> </td>
<td valign="top"><div id="photosgohere"></div></td>
</tr></table>
</body>
</html>
頁面呈現如圖 3:費城地圖在上,下方是標籤輸入框。輸入標籤後點擊地圖,就會依序發生三件事——取得地圖中心的座標(地圖可拖曳,所以每次中心可能不同)、以這組座標與標籤組出查詢字串發出 Ajax 呼叫、把 Flickr 回傳的符合照片顯示在右側。
圖 3 待你繼續加工的網頁
輸入標籤 Liberty 後點一下地圖,結果如圖 4:因為地圖停在費城,回來的是自由鐘的照片,以及其他掛上 Liberty 標籤的影像。
圖 4 在費城搜尋「Liberty」
點擊同時也會把地圖中心的座標印在地圖下方,費城大約在北緯 39 度、西經 75 度。這就是一個標準的 mashup:兩個資料來源併進同一個頁面,Google 的資訊經由 Ajax 交給 Flickr,最後同屏呈現地圖與照片。
Flickr 是很受歡迎的圖片站台,可以上傳照片、建立相簿、決定公開範圍。對開發者而言,它更是一座 API 寶庫——而這個 mashup 只需要其中一個方法:search。
先開一個 Flickr 帳號,再申請一組 Flickr API 金鑰。開發者該去的地方是 code.flickr,那裡有論壇、開發者部落格與完整的 API 文件。API 頁面提供了你開始所需的一切:概覽、服務條款、所有 API 呼叫清單與說明,還有一個試驗台(testbed)——這個功能特別好用,你勾好參數,它會直接吐出一條可以貼進程式碼的現成 URL。
所有 Flickr API 呼叫都共用同一個前綴:
https://api.flickr.com/services/rest/?method=
後面接上具體方法名稱,再帶 API 金鑰與該方法要求的參數。本教學用的是 search 方法,所以整串會長得像:
$url="https://api.flickr.com/services/rest/?method=flickr.photos.search"
其餘部分就是金鑰與方法專屬參數。search 方法接受經緯度,但只給一個點並不足以圈定搜尋範圍——它需要一個由四個地理座標圍成的邊界框(bbox),也就是一個矩形區域。
Google 地圖給的是中心點的兩個座標,透過 Ajax 送進 photos.php 後,在伺服器端由這兩個值算出四個值:經度與緯度各自加減 0.1 度。
$lonlow = urlencode($_GET['lon'] - 0.1); $lonhigh = urlencode($_GET['lon'] + 0.1); $latlow = urlencode($_GET['lat'] - 0.1); $lathigh = urlencode($_GET['lat'] + 0.1);
四個變數隨後被放進 API 呼叫裡:
bbox={$lonlow},{$latlow},{$lonhigh},{$lathigh}
緯度一度約等於 69 英里,因此相差 0.1 度所圍出的方框,邊長約 6.9 英里(取整為 7),面積約 49 平方英里。
標籤也可以複數。圖 5 用了兩個標籤 Philadelphia 與 zoo,中間以加號相連(Philadelphia+zoo),代表要找出同時具備這兩個標籤的照片,結果是一批動物照。操作前先拖動地圖,把費城動物園移到接近中心的位置。
圖 5 搜尋費城動物園
座標與標籤送到 photos.php,邊界框如上所述建立,接著組出帶著 API 金鑰與參數的 URL;另有一個非必要的參數 per_page,用來指定每頁回傳的照片數。
search 方法回傳的是資料而不是圖片本身——裡頭有指向照片在 Flickr 上位置的資訊,以及標題、擁有者等欄位。這段回應先經 cURL 的函式取得以便處理,再交給 PHP 的 simplexml_load_string,之後就能用 foreach 逐一走訪每個 XML 節點。
在迴圈裡,解析後的 XML 被重新組裝成連回 Flickr 照片頁的連結,由於連結指向縮圖,畫面上看到的就是縮圖;點縮圖即可看到原尺寸的照片。
基本版做完了,但如果你對費城沒興趣呢?改就好。接下來這個版本反過來——座標不再由地圖提供,而是由使用者輸入。地圖初始縮放拉到能看到美國全境,使用者輸入座標後點擊地圖,地圖便放大到該處,之後的搜尋流程一模一樣。
頁面上多了兩個欄位,分別填緯度與經度,如圖 6。
圖 6 需要輸入座標與標籤
以紐約市的 40.77 與 -73.94 為例,圖 7 是以 train 為標籤的搜尋結果。
圖 7 紐約的火車照片
| 城市 | 國家/地區 | 緯度 | 經度 |
|---|---|---|---|
| 北京 | 中國 | 39.85 | 116.38 |
| 柏林 | 德國 | 52.5 | 13.35 |
| 波士頓 | 美國 | 42.32 | -71.2 |
| 達拉斯 | 美國 | 32.82 | -96.72 |
| 丹佛 | 美國 | 39.8 | -104.9 |
| 拉斯維加斯 | 美國 | 36.2 | -115.3 |
| 倫敦 | 英國 | 51.46 | 0.01 |
| 莫斯科 | 俄羅斯 | 55.78 | 37.6 |
| 納什維爾 | 美國 | 36.2 | -86.8 |
| 新德里 | 印度 | 28.55 | 77.15 |
| 巴黎 | 法國 | 48.8 | 2.3 |
| 菲尼克斯 | 美國 | 33.36 | -112.1 |
| 里約熱內盧 | 巴西 | -23 | -43.3 |
| 羅馬 | 義大利 | 41.9 | 12.4 |
| 舊金山 | 美國 | 37.75 | -122.56 |
| 西雅圖 | 美國 | 47.62 | -122.3 |
| 悉尼 | 澳洲 | -33.84 | 151.2 |
| 多倫多 | 加拿大 | 43.7 | -79.4 |
| 溫哥華 | 加拿大 | 49.2 | -123.12 |
| 華盛頓 | 美國 | 38.9 | -77 |
別以為座標很容易找。上網搜這些城市,你會看到精度差異很大的各種版本;小數位數越多,精度越高。上表中的數值都曾在 Google 地圖上驗證並微調過,好讓城市正好落在地圖中心。
為了示範座標的用法,圖 8 在同一張 Google 地圖上標出了表中四座歐洲城市:柏林、倫敦、巴黎、羅馬。標記(marker)屬於一種覆蓋物,Google Maps API 文件中「覆蓋物」那一章有完整說明。
圖 8 依座標在地圖上打標記
建立這些標記的關鍵片段如下:
<script type="text/javascript">
function load() {
if (GBrowserIsCompatible()) {
var map = new GMap2(document.getElementById("map"));
map.setCenter(new GLatLng(48.8, 2.3), 4);
map.addOverlay(new GMarker(new GLatLng(52.5, 13.55))); // 柏林
map.addOverlay(new GMarker(new GLatLng(51.46, 0.01))); // 倫敦
map.addOverlay(new GMarker(new GLatLng(48.8, 2.3))); // 巴黎
map.addOverlay(new GMarker(new GLatLng(41.9, 12.4))); // 羅馬
}
}
</script>
縮放等級也會改變你看到的東西。縮得太遠時,即使座標有些偏差,畫面上也看不出錯——單純瀏覽地圖這樣還說得過去,但你的邊界框只有約 49 平方英里,偏差幾英里的座標,抓回來的照片可能與正確結果天差地遠,甚至一張都沒有。所以座標要盡量精準。
縮放等級由 setCenter 的第二個參數決定:數字越小視野越廣,越大則越放大。本教學各圖使用的值分別是——圖 5 為 14、圖 6 為 3、圖 7 為 10、圖 8 為 4。
Flickr 的 search 是彈性最大也最複雜的呼叫之一,可以附加三十多個參數。Flickr 的 API 專區有完整清單與可實際測試的試驗台。
接下來把主要搜尋方法調整一下,改以使用者 ID 搭配標籤。這樣你就能找出自己、或某位朋友家人的照片。user_id 是過濾的關鍵。
圖 9 的頁面只留標籤欄位,作者自己的 user_id 直接寫進 Flickr API 呼叫裡;使用者輸入的標籤被插入查詢字串,於是只有這位作者掛了該標籤的照片會出現。
圖 9 作者的照片
網頁與 photos.php 都為這個版本做了調整。地圖開啟時設定為華盛頓特區,點擊事件觸發 getPhotos() 時不再傳入座標:
function load() {
if (GBrowserIsCompatible()) {
var map = new GMap2(document.getElementById("map"));
map.setCenter(new GLatLng(38.9, -77), 11);
}
GEvent.addListener(map, "click", function() {
getPhotos();
});
}
photos.php 裡只用到傳入的標籤,user_id 寫死在 URL 中,經緯度與邊界框的計算則整段略去——華盛頓特區的位置已知。API 金鑰仍以 X 遮去,但 user_id 本來就能在 Flickr 上查到,不需要隱藏:
$url="https://api.flickr.com/services/rest/?method=flickr.photos.search
&api_key=xxxxxxxx&user_id=28770060%40N02&tags={$tags}";
回傳的照片一樣以縮圖連回較大的版本,點縮圖會跳到 Flickr 上的原圖頁。圖 10 就是點開圖 9 第一張照片後的樣子。
圖 10 照片的放大檢視
這個頁面右側還有不少資訊:作者的其他照片串(Flickr 術語稱 Photostream)、這張照片的標籤,以及因為做過地理標記而附帶的位置資訊。上傳時你甚至可能會驚訝地看到拍攝器材與拍攝日期被記了下來,Flickr 連瀏覽次數都會統計。
右側還有一個 More Properties 連結,點下去會看到更精確的細節:曝光時間、光圈、ISO 速度、解析度等。ISO 速度原本指的是底片的感光速率,數位相機不用底片,但這個係數沿用下來,仍是攝影上的重要參數。圖 11 就是同一張照片的完整資訊。
圖 11 照片的精確資訊
做 mashup 最重要的能力,是從外部資源取得資料,而這類資料多半透過 Web 服務與 API 呼叫取得。愈來愈多站台開放自己的 API 給開發者試用,一旦開始研究,很容易掉進「API 測試與 mashup 專站」的兔子洞裡。
多數 API 免費使用,因為站台希望藉此換來流量與知名度。常見的限制包括每日呼叫次數上限,以及把個人用途與商業用途分開處理——商業應用往往另有價格或其他要求。每個 API 服務都有自己的服務條款,動手之前務必讀清楚,免得日後扯上法律問題。