API on IT 空間

LiteLLM 串接需要 API Key 身分驗證的 Ollama API

jia@jiatool.com (Jia) — Sat, 24 Jan 2026 20:45:00 +0800

前言

上一篇我們為 Ollama 加了身份驗證，以提升安全性。

不過因為我有在使用 LiteLLM Proxy Server，需要為 LiteLLM 連 Ollama 時加上 API Key，但遇到了一些問題，最終改使用 Ollama 的 OpenAI 相容格式去串接成功~👍

* 延伸閱讀：透過 Nginx 為 Ollama 加上 API Key 身分驗證，提升安全性

也藉此記錄下來，供需要的讀者參考~

LiteLLM AI Gateway (LLM Proxy) 可以讓使用者透過統一介面呼叫不同的 API，並且可追蹤支出、Log 紀錄、為每個虛擬 API Key/使用者設定預算、負載平衡……等等功能。
如果是像公司、團體內，要提供不同 LLM API 給其他人使用，LiteLLM 或許是個不錯的工具。

[小廣告] 我製作了一款可愛的「企鵝魔法師」貼圖~
歡迎下載：LINE 貼圖、Telegram 貼圖 (免費)

設定 LiteLLM Config

需要為 LiteLLM 連 Ollama 時加上 API Key。

* 以下是在 config.yaml 內設定。

原本我想說簡單，在 config.yaml 裡加上 api_key 欄位就行，但試了幾次發現 api_key 不會被帶上 (從 LiteLLM 的 source code 查也確實在連 Ollama 時不會帶上 api_key)。

後來我想到 Ollama 也支援 OpenAI API 相容格式，或許 LiteLLM 改使用 OpenAI 格式去串接我的 Ollama 可行。
經過實測，確實 OK~

model_list:
- model_name: gpt-oss:20b
litellm_params:
model: openai/gpt-oss:20b
api_base: "http://abc.com:11434/v1"
api_key: "sk-123456"

也可以將 api_base 和 api_key 設定移到環境變數，並透過以下方式帶入：

model_list:
- model_name: gpt-oss:20b
litellm_params:
model: openai/gpt-oss:20b
api_base: "os.environ/OLLAMA_API_BASE"
api_key: "os.environ/OLLAMA_API_KEY"

環境變數像我使用 K8S 就如下設定：

env:
- name: OLLAMA_API_BASE
value: 'http://abc.com:11434/v1'
- name: OLLAMA_API_KEY
value: sk-123456

結語

有遇到同樣問題的讀者，可以參考我的作法~

對生成式 AI 感興趣的讀者，記得追蹤 FB 粉專『 IT空間』，以免錯過最新的發文通知呦~🔔

參考：
LiteLLM | GitHub
LiteLLM 官方文件

成功路上並不擁擠，因為堅持的人不多。

GitHub Models 讓你免費玩 GPT、Llama、Phi，還提供 API 串接

jia@jiatool.com (Jia) — Sat, 11 Jan 2025 21:15:00 +0800

2025-04-12 更新 GitHub Token 權限設定

前言

我前陣子才發現，原來 GitHub 上面也有可以免費使用的 LLM，像是 GPT-4o、Llama-3.3、Phi-3.5…等等，甚至還提供 API 可串接程式！

雖然 GitHub Models 主要是讓我們在開發生成式 AI 應用程式測試用，算是試用性質，所以有速率 & Token 數量限制，但我覺得用作個人專案還蠻不錯的，每日請求上限也不算太少 (50~150 次，依模型而定)，有需求的網友可以試試~

GitHub Models

如果你發現還不能使用，可加入候補名單：https://github.com/marketplace/models/waitlist

速率限制

在開始使用之前，首先來看看它速率限制到底是多少。

Rate limits | GitHub Docs

GitHub Models 使用速率限制

GitHub Models 是依照模型分成 Low、High、Embedding 等級去做限制，
在模型介紹和 Playground 頁面都有寫此模型是採用哪個限制等級 ("Rate limit tier")。

* 表格底下雖然還有 Azure OpenAI o1-preview 和 Azure OpenAI o1-mini，但我好像沒辦法使用。

例如 GPT-4o 是 "High"，那它的限制就是：

每分鐘請求數：10 次
每天的請求數：50 次
每個請求的 Tokens：輸入 8000, 輸出 4000
並發請求：2 個

* 當然假如你是 Copilot Business 或 Copilot Enterprise，那可使用次數就會更多。

模型清單

GitHub Models 有提供哪些模型讓我們試用呢？

這邊有完整支援的模型清單：https://github.com/marketplace?type=models

GitHub Models 支援模型清單

例如聊天的模型有：

OpenAI GPT-4o
OpenAI GPT-4o mini
DeepSeek-V3-0324
DeepSeek-R1
Llama 4 Maverick 17B 128E Instruct FP8
Llama-3.3-70B-Instruct
Llama-3.2-90B-Vision-Instruct
Phi-4
Phi-3.5-MoE instruct
Phi-3.5-vision instruct
Mistral Large
Mistral Small 3.1
Codestral 25.01
Cohere Command R+
AI21 Jamba 1.5
JAIS 30b Chat
…(更多)

還有 Embedding 嵌入模型：

OpenAI Text Embedding 3
Cohere Embed v3 Multilingual
…(更多)

點選任一個模型後，會進入模型介紹頁面。

會有模型的相關說明介紹、測試評估分數、License 等等，右邊區塊還有像是簡介、Context (模型"本身" 輸入、輸出 tokens 限制)、訓練資料日期、速率限制等級 (Rate limit tier)、提供者、支援語言等等資訊。

模型介紹頁面

Playground

從剛剛 "模型介紹頁面" 點擊右上角「Playground」，或在 GitHub Marketplace 左上角選擇一個模型。
即可進入 Playground 頁面跟它聊天。

* 例如 GPT-4o 的 Playground

模型 Playground 頁面

先看右側區塊可以切換 "Parameters" 和 "Details"：

Parameters：設定、調整模型參數 (System prompt、Response format、Max Tokens、Temperature……)。
Details：模型的相關說明 (就跟剛剛的模型介紹頁面差不多)。

再來看左側區塊分為 "Chat"、"Code"、"Raw"：

Chat：如同使用 ChatGPT、Gemini 一樣，可以與模型做多輪的聊天。
Code：展示 API 如何使用，有不同程式語言的範例，下一節 API 還會介紹。
Raw：你與模型對話紀錄的原始資料。

另外，
在頁面左上方還可以看到「Compare」按鈕，用於比較兩種不同模型的回答，在你輸入問題(prompt)後，它會同時送給兩個模型，讓你方便比較兩種模型哪個回覆比較好。

比較兩種不同模型的回答

如果你想將目前調整好的參數、聊天記錄儲存起來 (甚至分享)，可以使用右上角的「Preset」功能。

API

如同文章標題提到的，除了在網頁使用 Playground 介面，GitHub Models 還提供 API 供我們串接自己的程式做測試。

創建 GitHub Token

在開始使用 API 之前，我們要先去 GitHub 建立 Token，用作身份驗證。

* 關於 GitHub 的 Token 介紹，可以參考這篇官方文件： Managing your personal access tokens

Settings > 左側最下方 Developer settings > Personal access tokens > Fine-grained tokens

點選 Generate new token。

Expiration 過期時間可以改成 "No expiration" (無期限)。

Repository access 欄位維持 "Public Repositories" 即可。

Expiration、Repository access 欄位設定

重點：
Permissions > Account permissions > Models 要改為 "Read-only"，這樣才有 GitHub Models 的權限。

Permissions > Account permissions > Models 權限

填寫完欄位後，最下方點擊 Generate token 按鈕。

創建新的 Token

將 token 複製並保存好，之後忘記就只能再重新產生了。

Fine-grained personal access token 會長的類似這樣：github_pat_11AHxxxxxxxxxxxxxxxxxxxxxxxxxCp7pLSr3a

將 Token 複製存起來，之後就沒辦法再看到了

使用範例

回到剛剛 Playground 頁面的 "Code" 分頁 (像是 GPT-4o 的 Playground )。

右上角可以下拉清單選擇不同的程式語言、SDK (OpenAI SDK 或 Azure AI Inference SDK)。

切到 REST 語言，可以看到實際發送請求的 URL、Headers、Body 等等，API 格式是跟 OpenAI API 一樣的，所以如果你使用的套件、框架、軟體有支援 OpenAI API 格式，那就可以直接切換來用，或者以後 GitHub Models 測試完要換到穩定的付費 Azure OpenAI、OpenAI 也很簡單。

官方範例程式碼

這邊我使用 Postman 來示範如何發送請求。

API URL、Headers 的設定

Request URL: https://models.inference.ai.azure.com/chat/completions
Request Method: POST
Request Headers:

Content-Type: application/json
Authorization: Bearer github_pat_11AHxxxxxxxxxxxxxxxxxxxxxxxxxCp7pLSr3a

* Authorization 內 Bearer 後面那串就是剛剛創建的 personal access token。

API Body 的設定

Body (JSON 格式)：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
"messages": [
{
"role": "system",
"content": ""
},
{
"role": "user",
"content": "你是誰？"
}
],
"model": "Llama-3.3-70B-Instruct",
"temperature": 0.8,
"max_tokens": 2048,
"top_p": 0.1
}

* 只有 messages 和 model 欄位是必要的

回傳資料範例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


{
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"content": "我是一個人工智慧語言模型，稱為LLaMA。LLaMA是Meta開發的一種人工智慧模型，旨在處理和生成類似人類的語言。",
"role": "assistant",
"tool_calls": null
}
}
],
"created": 1734225172,
"id": "cmpl-6c7bdcda-1211-4f5a-b9fc-2f2526465445",
"model": "Llama-3.3-70B-Instruct",
"object": "chat.completion",
"usage": {
"completion_tokens": 47,
"prompt_tokens": 39,
"total_tokens": 86
}
}

* 不過我在猜它是不是還會塞入其他 prompt，因為 usage > prompt_tokens 看起來明顯大於我下的 prompt token 數量。知道的網友可以留言幫我解惑~🙏

結語

如果你剛好在開發 LLM 應用專案，或使用量不多，推薦可以嘗試 GitHub Models。

如果對於生成式 AI 有興趣的讀者，記得追蹤『 IT空間』FB 粉專，才不會錯過最新的發文通知呦~🔔

參考：
GitHub Marketplace Models
GitHub Models 說明文件

我不是最好的那個，但我想成為最努力的那個。

—— 李洋 (台灣羽球國手)

[Metabase 系列] Metabase API 使用教學，輕鬆串接自己的系統

jia@jiatool.com (Jia) — Fri, 18 Oct 2024 15:10:00 +0800

前言

前幾篇我們學會了安裝 Metabase、建立提問和圖表、建立 Dashboard，那你有沒有想過能否把 Metabase 串接到自己的系統內呢？例如可以做一些自動化執行任務，或需要大量批次處理。

其實 Metabase 本身就有提供很完善的 API。應該說，Metabase 本身連接前端和後端，就是使用這組 API，所以幾乎你在 Metabase 執行的所有操作，都有對應的 API 端點可以使用。

今天我們來學習一下如何使用 Metabase API。

Metabase 系列教學文章：

* 本文使用 Metabase 版本為：v0.50.28

圖片來源：Metabase 官網

Metabase API

Metabase 本身連接前端和後端，就是使用這組 API，所以幾乎我們在 Metabase 可以執行的所有操作，都有對應的 API 端點。
例如新增資料庫、建立提問、建立 Dashboard、人員權限設定、管理員設定、搜尋功能…

* 這邊有官方的 API 教學和 API documentation 可以參考。

但該如何知道，我們想要的功能該用哪個 API 端點，以及需要帶上哪些參數呢？

有三種方法可以來尋找：

從 Metabase API documentation
在 API live docs 進行測試
使用瀏覽器的開發人員工具

Metabase API documentation 就是官方整理的文件，可以快速查詢。

但有些看出不出參數要如何帶入，以及它回傳資料的內容與格式，所以我自己比較常用 "開發人員工具" 的方式來查詢。
(API live docs 好像是最近才加入的功能)

Metabase API documentation

API live docs 是可以在你自己運行的 Metabase 上，查看透過 RapiDoc 提供的即時 OpenAPI 文件。只要前往 /api/docs 路徑 (例如 http://localhost:3000/api/docs)。

左邊清單可以方便找到 API 端點，點擊右方的 "TRY" 會發送請求，並且會顯示回傳的結果，挺方便的。

API live docs

而瀏覽器的開發人員工具，就跟我們在寫網站或網路爬蟲時，使用的方式一樣。

開啟瀏覽器的 開發人員工具 (F12 或 Ctrl + Shift + i)，切換到 "Network" > "Fetch/XHR" 分頁。

瀏覽器的開發人員工具

"Headers" 頁面可以查看請求的網址與方法
"Payload" 頁面可以查看請求的 Body
"Preview" 頁面可以查看請求的回傳結果

瀏覽器的開發人員工具

API 金鑰 (API key)

剛剛我們再查看有哪些 API 端點時，因為是在登入的瀏覽器內操作，所以它有自動帶上我們的身分認證，但之後要整合進我們的程式或專案，那就需要使用 API 金鑰做身分認證。

在 Metabase 裡右上角齒輪 > 管理員設定 > 設定 > 授權認證 > API 金鑰。

右上角齒輪 > 管理員設定

管理員設定內設定 > 授權認證 > API 金鑰

點擊「建立 API 金鑰」。

金鑰名稱自己取一個，純粹為了區分用。
接下來要選擇一個群組，該 API 金鑰會擁有與此群組相同的權限。

建立 API 金鑰

建立後，它會顯示完整的 API 金鑰，這時候要將其複製並保存起來。

複製 API 金鑰

之後只能編輯 API 金鑰名稱跟改群組，金鑰內容忘記就只能再產生新的了。

編輯 API 金鑰

在使用 API 時，只要將此 API 金鑰帶入 Headers 內即可：

x-api-key: YOUR_API_KEY

關於其他說明，可以參考官方文件 API keys 。

Session Token

除了使用 API key 驗證以外，其實還可以使用 session token 來驗證，這個就等同輸入帳號密碼的方式。

(在以前的版本，還沒有 API key 的時候，就只能透過 session token 驗證，不過它過一段時間後會過期，需要再重新取得，現在新版都建議直接使用 API key 即可)

* 帳號是 email 格式，例如 person@metabase.com

curl -X POST \
-H "Content-Type: application/json" \
-d '{"username": "帳號", "password": "密碼"}' \
http://localhost:3000/api/session

它會回傳像是 { "id": "38f4939c-ad7f-4cbe-ae54-30946daf8593" }。

之後在使用 API 時，將此 id 帶入 Headers 內：

X-Metabase-Session: 38f4939c-ad7f-4cbe-ae54-30946daf8593

* 預設情況，session token 有效期為 14 天。可以透過設定環境變數 MB_SESSION_AGE （值以分鐘為單位）來修改持續時間。
* 最好將 session token 保存起來重複使用，直到過期再重新取得。因為安全因素，使用帳密取得 ession token 有速率限制。

API 如何使用

在整合進我們的程式或專案之前，可以先使用 HTTP Request、測試 API 的工具，例如 Postman 來先測試，方便我們理解該如何使用、回傳資料長怎樣。

以下就以最有名的 Postman 工具來示範。

我們就以取得「全部群組的清單」來當第一個例子。
* 官方 API 文件： GET /api/permissions/group

Request URL：http://localhost:3000/api/permissions/group
Request Method：GET
Headers：
x-api-key:mb_GEeE7gBEcObtBFvanzyeTMIBzvCUmhEvjYv729OCkIA=
(請換成自己剛剛建立的 API 金鑰)

Send 送出請求後，可以收到回覆，這就是我們目前的全部群組：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


[
{
"id": 2,
"name": "Administrators",
"entity_id": null,
"member_count": 2
},
{
"id": 1,
"name": "All Users",
"entity_id": null,
"member_count": 4
}
]

Postman 取得全部群組的清單

還記得剛剛建立 API 金鑰時，有指定一個群組嗎？
我們是選擇「Administrators」，代表它有管理者的權限。那假如我們再創建一個「All Users」群組的 API 金鑰，測試同一個 API 呢？

可以看到它回覆 "您沒有權限那麼做"，HTTP Status Code 是 403 Forbidden，代表客戶端沒有訪問該資源的權限，這就是權限管控。

就跟一般使用者登入 Metabase 後，他也沒有權限進入 "管理員設定" 一樣。

Postman 取得全部群組的清單 (沒權限)

再來試一個。

我想查看一個「提問 (Questions，也就是圖表) 的資訊」，該如何操作？

* 在 API 中，提問被稱為卡片(card)
* 官方 API 文件： GET /api/card/:id

例如網址是在 http://localhost:3000/question/27-products 的圖表。

card id 就是在網址後面的數字，以上範例的話就是 27。

提問 (Questions，也就是圖表) 的網址

Request URL：http://localhost:3000/api/card/27
Request Method：GET
Headers：
x-api-key:mb_j6OtF0o24wnnJb3A/wteFfuilW4lKyKHtx9Cl6cQKBE=
(請換成自己剛剛建立的 API 金鑰)

Send 送出請求後，可以收到回覆，就是有關這個提問(圖表)的資訊：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


{
"id": 27,
"name": "Products 依類別分組",
"description": null,
"archived": false,
"view_count": 2,
"type": "question",
"query_type": "query",
"display": "bar",
"database_id": 1,
"can_write": true,
"average_query_time": 38.0000000000000000,
"enable_embedding": false,
"last_query_start": "2024-10-12T13:07:51.402753Z",
"last_used_at": "2024-10-12T13:07:51.422213Z",
"updated_at": "2024-10-12T13:31:43.873511Z",
"created_at": "2024-10-12T13:07:21.456419Z",
"creator_id": 1,
...以下省略
}

Postman 取得提問 (圖表) 的資訊

以上兩個範例都是 GET 資料，來看看假如是想要 POST 的請求方式呢？

例如想取得「提問 (Questions，圖表) 的查詢資料」，也就是網頁底下切換成原始資料的部分。

提問 (圖表) 的查詢資料

* 官方 API 文件： POST /api/card/:card-id/query

Request URL：http://localhost:3000/api/card/27/query
Request Method：POST
Headers：
x-api-key:mb_j6OtF0o24wnnJb3A/wteFfuilW4lKyKHtx9Cl6cQKBE=
(請換成自己剛剛建立的 API 金鑰)
Body:
{
"ignore_cache": true
}

* 這個 API 端點的 Body 非必要，可以省略

Send 送出請求後，可以收到回覆，是這個提問(圖表)的查詢資料：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


{
"data": {
"rows": [
[
"Doohickey",
42
],
[
"Gadget",
53
],
[
"Gizmo",
51
],
[
"Widget",
54
]
],
...以下省略
},
"cached": null,
"database_id": 1,
"started_at": "2024-10-12T13:42:49.532062Z",
"status": "completed",
"context": "question",
"row_count": 4,
"running_time": 25,
...以下省略
}

Postman 取得提問 (圖表) 的查詢資料

其他更多說明與 API 端點，可以參考 Metabase 官方 API documentation 。

備註

雖然他們有說，API 介面盡量不會做更改，但新功能推出、舊 bug 修復可能多多少少 API 還是有調整，因此在升級 Metabase 版本之前，可以先參考官方整理的文章： API 介面的重大更改

結語

在以上了解 Metabase API 的使用之後，我們就可以把 Metabase 串接到自己的系統內，做更深度的整合，或做些自動化的應用了~

而且從 API 回傳資料，也可以發現一些沒有顯示在網頁畫面上的資訊 XD

如果對於 Metabase 有興趣的讀者，記得『 IT空間』FB 粉專要追蹤起來，才不會錯過最新的發文通知哦~🔔

參考：
Metabase 官方網站
 Metabase API 官方教學
 Metabase 官方 API documentation
Metabase 官方 GitHub
Metabase API 介面的重大更改

有那個時間絕望的話，還不如去吃好吃的美食，然後好好睡一覺。

—— 《法醫女王》(日本電視劇)

Bright Data 手把手教學 — 輕鬆取得 Google、Yahoo 搜尋引擎結果 API

jia@jiatool.com (Jia) — Sat, 23 Dec 2023 21:00:00 +0800

此篇為商業合作文章

前言

Bright Data 跟我之前介紹過的 DataForSEO 、 Aves API 一樣，都有提供抓取搜尋引擎結果的服務，因此照理說穩定度應該會比較好，不過 Bright Data 是專注於商務客戶，所以要提醒目前個人是無法使用的 (不支持個人用途，如打遊戲之類的)。

Bright Data 的 SERP API 目前支援 Google、Bing、DuckDuckGo、Yandex、Yahoo、百度和 Naver 搜尋引擎，你可以用來做關鍵字追蹤、比較價格、市場研究、偵測版權侵權、廣告情報等等用途。

底下我會以最多人使用的「Google 搜尋 API」來當範例，一起從註冊、設定、測試到最後程式碼帶大家認識。

Bright Data 官網

註冊 Bright Data

首先，需要有一組 Bright Data 帳號。

如果願意透過此連結註冊，我可以獲得一絲絲分潤，就當支持我寫作吧~🫡

註冊 Bright Data 帳號：https://get.brightdata.com/fabjye

官方還提供我的讀者優惠~
透過上述連結註冊的新用戶，首次儲值 25 美元再送 25 美元，直接省一半!!

需要填寫姓名、工作用 Email、公司規模，就像文章一開始說的，它是面向商務的服務。
(不支持個人用途)

註冊 Bright Data

註冊後，在添加付款方式時，將收到 5 美元的額度可以讓你試用。或者可以聯絡你的客戶經理，會贈送一些額度可以讓你免費試用。

SERP API

SERP API 目前支援以下幾種搜尋，可以看出來涵蓋蠻多的：

Google Search
Google Images
Google Videos
Google Maps
Google Trends
Google Reviews
Google News
Google Jobs
Google Shopping
Google Hotels
Bing Search
DuckDuckGo Search
Yandex Search
Yahoo Search
百度 Search
Naver Search

SERP API 價格

SERP API 價格官方有詳細說明在這個網頁，

依照方案分為四種：PAY AS YOU GO、GROWTH、BUSINESS、ENTERPRISE。

CPM 指的是每一千次請求 API 的價格。
以方案 GROWTH 為例，$2.30/CPM 就是每一千個請求要 2.3 美金，等同於每個請求 0.0023 美金 (約 0.072 新台幣)。

GROWTH 和 BUSINESS 方案會有每月最低消費金額 (分別為 500 和 1000 美金)，但它們使用 API 的價格就會再便宜一些些。

* 以上價格為美金💵
* 針對費用、週期計算有疑慮的讀者，建議可以直接諮詢客戶經理。

SERP API 價格

建立新的 SERP API Zone

第一次使用可以先參考這篇官方文章去設定，或直接跟著我底下的教學來實作。

進到 " My Proxies " 頁面，找到「SERP API」點 "Get started" 來新增一個 Solution。

My Proxies > SERP API > Get started

接下來，設定一個 Solution 名稱 (在 Bright Data 內也等同 zone 名稱)，注意這個設定後就無法更改 (就只能把它刪除，再建一個新的)，其餘設定都可以之後再更改。

設定一個 Solution

SERP API Zone 上方可以看到有三個頁籤，可以自己隨意點點看看：

Access parameters (存取參數)
Configuration (配置)
Statistics (統計數據)

* 有幾個資訊後續 call API 時會用到，我也在這邊先標出來："host"、"account id"、"password"、"zone"。

SERP API Zone 設定

* Access parameters (存取參數)分頁底下有個 Limit 欄位，可以設定請求量限制，當到達限制後要關閉還是通知你，可以避免不小心意外耗費太多額度。

可限制 API 使用，避免超額

測試與範例頁面

Bright Data 也同樣提供 SERP API 相關測試與參數介紹頁面，在開始撰寫程式前，可以先來這邊透過網頁 UI 的方式嘗試、熟悉各參數與如何使用。

* 官方介紹中有看到支援 Google、Bing、DuckDuckGo、Yandex、Yahoo、百度和 Naver 搜尋，不過在這個頁面缺少百度、Yahoo、Naver，經過我向官方詢問，使用方式與參數都是一樣的，所以如果需要，稍微改一下應該就能使用了。

Playground - 測試頁面

在 SERP API Playground 測試頁面，透過 UI 介面選擇瀏覽器、設定關鍵字與參數 (下圖橘框處)，並實際查看它查詢後回傳的資料 (網頁與 JSON)，

而且使用 Playground 是 "免費" 的！！👍
你可以先在這邊先用不同關鍵字、參數去測試，沒問題後再整合進程式裡面。

SERP API Playground 測試頁面

下方有個 "Generate API code" 按鈕 (上圖藍框處)，可以查看假如依照你目前的參數設定，該如何下查詢指令(或程式碼)。
要注意你 proxy 設定 "同步" 或 "非同步" 請求 (下一個章節會說明)，這邊的範例也會跟著改變。

但有點可惜的是，"非同步請求" 的程式碼範例只有 Shell 跟 Node.js，而"同步請求" 雖然有 Python 範例，但不是使用我習慣的 Requests 套件，因此我花了一些時間研究與嘗試，後面章節我有將程式碼列出來供大家參考，

Generate API code 範例程式

* 如果你還沒註冊就等不及的話，可以到 SERP API 介紹網頁中的 SERP API Live Demo 先嘗試，不過就只有讓你測試 Google 搜尋就是了。

SERP API Live Demo

API Guide - 參數介紹與指令

這個 API Guide 頁面是介紹 SERP API 支援那些參數，以及該如何下這些參數。對於參數不了解的話，也可以先到這邊來看看。

同樣這頁也會因為你 proxy 設定 "同步" 或 "非同步" 請求，而有所對應改變。

SERP API Guide - 參數介紹與指令

發送請求

它的 SERP API 也有分成「同步請求」、「非同步請求」兩種請求方法。

預設是使用同步請求，使用上最簡單，只需要發送一個請求即可。但對於有大量請求需求的使用者，還是建議使用非同步請求，因為它有比較好的穩定性。

如果想切換同步/非同步請求，則在 SERP API Zone > Configuration 的最下面，有個「Asynchronous requests」開關

SERP API 切換同步/非同步請求

官方範例是使用我不熟悉的套件，但我比較習慣使用 requests 套件，因此底下範例程式是我自己改寫的~✍️

同步請求

只要發送一個 GET 請求即可取得結果。

它是透過 proxy 將請求轉給他們，proxy 設定為：
http://brd-customer-{ACCOUNT_ID}-zone-{ZONE}:{PASSWORD}@{HOST}
完整樣子會像是：
http://brd-customer-oooooooo-zone-serp_api:xxxxxxxx@brd.superproxy.io:22225

另外，出於資訊安全的考量，進行 HTTPS 連線時 Python 會檢查伺服器的 SSL 憑證是否有效，因此還需要安裝 SSL 憑證，否則會出現像下圖那樣的錯誤，可以參考官方文章：如何安裝 SSL 憑證

遇到 SSL 憑證問題

那假如只是要測試，我們可以 “忽略憑證” (verify=False，參考這篇文章 )，如同下方範例程式馬。

參數說明可以參考這篇，或者如果已經登入，可以在後台的 API Guide 頁面去查看各種查詢與參數該如何下。

Python 程式碼範例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


url = 'https://www.google.com.tw/search'
params = {
"q": "Google Gemini", # 搜尋關鍵字
"gl": "tw",
"num": "100",
"brd_json": "1" # 回傳 JSON 格式，預設是 html
}
proxy_url = f"http://brd-customer-{ACCOUNT_ID}-zone-{ZONE}:{PASSWORD}@{HOST}"
proxies = {'http': proxy_url, 'https': proxy_url}
# 使用 verify=False 忽略 SSL 憑證
# 為了安全，建議還是安裝 SSL 憑證：https://help.brightdata.com/hc/en-us/articles/4413322250001
response = requests.get(url, params=params, proxies=proxies, verify=False)
print(response.json())

* 各個狀 SERP API 錯誤訊息意思如這個官方清單。

非同步請求

在說明用法之前，我們要先去產生一組 API Token ( 官方說明文章 )。

到後台的 Account Settings > User access 頁面，點擊最下方 API tokens 的右邊 "Add token" 按鈕。

Account Setting > Add token

並指定要給哪一位 User 使用，Permission 就選擇 "User" 即可，期限可以指定日期或勾選下方的"Unlimited (無期限)"。

* 因為這關係到權限，可能會需要去信箱收驗證信。

Add API token

它產生的 API Token 要複製起來，不然之後忘記就要重新產生了。

再來到你的 SERP API Zone 中 Configuration 分頁，最下方將「Asynchronous requests」開關打開。

SERP API 切換同步/非同步請求

這邊的 "Web Hook URL" 和 "Web Hook Request Method" 你可以設定，讓任務完成後會主動來呼叫你，或者像我下面將要說明的 — 由我們自己去取得結果，那就不需要填這兩個欄位了。

記得要 Save。

好了，終於要來講 "非同步請求" 該怎麼使用了。

它與 "同步請求" 使用方式有所不同，"非同步請求" 使用上分為兩個請求：

設定任務
取得任務的查詢結果

先使用 POST 請求「設定任務」，指定查詢參數、回傳格式。
如果成功的話，會在收到回覆的 Header 看到一個 "x-response-id"，這個代表 Response ID，也就是下一步要使用的。

第二步，送出 GET 請求「取得任務的查詢結果」，帶上第一步取得的 x-response-id。
如果查詢任務已完成，會收到 Status Code = 200，Body 內容即是查詢結果資料；如果查詢任務還沒完成，收到 Status Code = 404 (Not Found)，那就要等個幾秒再試一次。

可以直接參考下方範例程式碼，或參考這篇官方說明。

* 當然只有 "設定任務" 請求會收費 (如果成功的話)。
* 查詢結果最多會存在伺服器 24 小時，這段時間你還是可以使用 Response ID 去取得查詢結果。

Python 程式碼範例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


# 記得要先去後台開啟 Asynchronous requests
url = f'https://api.brightdata.com/serp/req?customer={ACCOUNT_ID}&zone={ZONE}'
headers = {
'Content-Type': 'application/json',
'Authorization': f'Bearer {API_TOKEN}'
}
data = {
"country": "tw",
"query": {
"q": "Google Gemini", # 搜尋關鍵字
"gl": "tw",
"num": "100"
},
"brd_json": "json" # 回傳 JSON 格式，預設是 html
}
response = requests.post(url, headers=headers, json=data)
response_id = response.headers.get("x-response-id")
print(f"response id: {response_id}")
time.sleep(10) # 等待它完成查詢
url = f'https://api.brightdata.com/serp/get_result?customer={ACCOUNT_ID}&zone={ZONE}&response_id={response_id}'
headers = {'Authorization': f'Bearer {API_TOKEN}'}
response = requests.get(url, headers=headers)
print(response.json())

* 各個狀 SERP API 錯誤訊息意思如這個官方清單。

查詢結果說明

SERP API 回傳的查詢結果我以 JSON 格式來說明，以下直接貼出範例結果給大家參考，大部分欄位應該很容易就看出來意思。

其他說明可以直接參考官方說明：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67


{
"general": {
"search_engine": "google",
"results_cnt": 2030000000,
"search_time": 0.31,
"language": "zh-TW",
"mobile": false,
"basic_view": false,
"search_type": "text",
"page_title": "Google Pixel - Google 搜尋",
"timestamp": "2023-12-03T14:27:44.026Z"
},
"input": {
"original_url": "https://www.google.com.tw/search?q=Google+Pixel&gl=tw&lang=zh-TW&location=Kaohsiung+City%2CTaiwan&brd_json=1",
"request_id": "xxxxxxxx"
},
"organic": [
{
"link": "https://store.google.com/tw/category/phones?hl=zh-TW",
"display_link": "https://store.google.com › category › phones",
"title": "Google Pixel 手機- Google 商店",
"description": "Google 5G smartphones feature the latest technology so you always have that new phone feeling. Find out which Pixel is right for you.",
"rank": 1,
"global_rank": 1
},
{
"link": "https://store.google.com/tw/?hl=zh-TW",
"display_link": "https://store.google.com › ...",
"title": "Google 商店官網，專售Google 製造的裝置和配件",
"description": "全新Pixel 手機內建Google AI 技術，搭載最令人驚艷的Pixel 相機。 ... 支援大多數搭載Android 9.0 以上版本的手機，須有Google 帳戶、Google Pixel Watch 應用程式和網路連 ...",
"rank": 2,
"global_rank": 2
},
......
{
"link": "https://guidebooks.google.com/pixel?hl=zh-Hant",
"display_link": "https://guidebooks.google.com › pixel",
"title": "瞭解「Google Pixel」",
"description": "設定新的Pixel 手機. 瞭解如何從你的舊Android 手機或iPhone® 轉移資料。 接下來，你可以學習如何自訂各項設定、取得日常事務協助以及 因應緊急狀況等等。",
"rank": 10,
"global_rank": 10
}
],
"pagination": {
"current_page": 1,
"next_page_link": "https://www.google.com.tw/search?q=Google+Pixel&sca_esv=587474982&gl=tw&hl=zh-TW&ei=XZBsZxxxxxxxx4HIDg&start=10&sa=N",
"next_page_start": 10,
"next_page": 2
},
"related": [
{
"list_group": false,
"link": "https://www.google.com.tw/search?sca_esv=587474982&gl=tw&hl=zh-TW&q=google+pixel%E8%A9%95%E5%83%B9&sa=X&ved=2ahUKEwiS9uLuvPOCAxXYBogKHdNVAOkQ1QJ6BAgjEAE",
"text": "google pixel評價",
"rank": 1,
"global_rank": 11
},
......
{
"list_group": false,
"link": "https://www.google.com.tw/search?sca_esv=587474982&gl=tw&hl=zh-TW&q=google%E6%89%8B%E6%A9%9Fpixel+7&sa=X&ved=2ahUKEwiS9uLuvPOCAxXYBogKHdNVAOkQ1QJ6BAgeEAE",
"text": "google手機pixel 7",
"rank": 8,
"global_rank": 18
}
]
}

完整 Python 範例

首先要確認有安裝 Requests 套件：

1

pip install requests

完整 Python 程式碼：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106


import time
import json
import requests
ZONE = "<your_zone>"
ACCOUNT_ID = "<your_account_id>"
PASSWORD = "<your_password>"
HOST = "<your_host>"
API_TOKEN = "<your_api_token>"
class Brightdata():
def __init__(self, zone, account_id, password, host, api_token):
self.zone = zone
self.account_id = account_id
self.password = password
self.host = host
self.api_token = api_token
self.username = f"brd-customer-{self.account_id}-zone-{self.zone}"
self.proxy_url = f"http://{self.username}:{self.password}@{self.host}"
def sync_get_search_result(self, keyword):
""" SERP API 同步請求 - 取得搜尋結果"""
proxies = {
'http': self.proxy_url,
'https': self.proxy_url
}
url = 'https://www.google.com.tw/search'
params = {
"q": keyword, # 搜尋關鍵字
"gl": "tw",
"lang": "zh-TW",
"location": "Kaohsiung City,Taiwan",
"num": "100",
"brd_json": "1" # 回傳 JSON 格式，預設是 html
}
# 使用 verify=False 忽略 SSL 憑證
# 為了安全，建議還是安裝 SSL 憑證：https://help.brightdata.com/hc/en-us/articles/4413322250001
response = requests.get(url, params=params, proxies=proxies, verify=False)
if response.status_code != 200:
print(f"Error: {response.status_code} - {response.reason}")
return {}
return response.json()
def async_set_search_job(self, keyword):
""" SERP API 非同步請求 - 設定搜尋任務

 * 記得要先去後台開啟 Asynchronous requests
 """
url = f'https://api.brightdata.com/serp/req?customer={self.account_id}&zone={self.zone}'
headers = {
'Content-Type': 'application/json',
'Authorization': f'Bearer {self.api_token}'
}
data = {
"country": "tw",
"query": {
"q": keyword, # 搜尋關鍵字
"gl": "tw",
"lang": "zh-TW",
"location": "Kaohsiung City,Taiwan",
"num": "100"
},
"brd_json": "json" # 回傳 JSON 格式，預設是 html
}
response = requests.post(url, headers=headers, json=data)
response_id = ""
if response.status_code == 200:
response_id = response.headers.get("x-response-id")
print(f"response id: {response_id}")
else:
print(f"Error: {response.status_code} - {response.reason}")
return response_id
def async_get_search_result(self, response_id):
""" SERP API 非同步請求 - 取得搜尋結果
 """
url = f'https://api.brightdata.com/serp/get_result?customer={self.account_id}&zone={self.zone}&response_id={response_id}'
headers = {'Authorization': f'Bearer {self.api_token}'}
response = requests.get(url, headers=headers)
if response.status_code != 200:
print(f"Error: {response.status_code} - {response.reason}")
return {}
return response.json()
if __name__ == '__main__':
brightdata = Brightdata(ZONE, ACCOUNT_ID, PASSWORD, HOST, API_TOKEN)
# SERP API 同步請求
result = brightdata.sync_get_search_result("Google Pixel")
print(json.dumps(result))
# SERP API 非同步請求
# response_id = brightdata.async_set_search_job("Google Pixel")
# time.sleep(10) # 等待它完成查詢
# result = brightdata.async_get_search_result(response_id)
# print(json.dumps(result))

* 官方還有更多的說明文件，有需要都可以進去看看：

如果願意透過此連結註冊，我可以獲得一絲絲分潤，就當支持我寫作吧~🫡

註冊 Bright Data 帳號：https://get.brightdata.com/fabjye

官方還提供我的讀者優惠~
透過上述連結註冊的新用戶，首次儲值 25 美元再送 25 美元，直接省一半!!

結語

如果你有爬取(抓取)搜尋結果資料的需求，我覺得花點小錢還是蠻值得的，總比自己在那邊搞爬蟲、驗證碼(CAPTCHA)、換 IP、Proxy、被Ban帳號好太多了… (<- 過來人😭😭😭

Bright Data 除了這次介紹的 SERP API 工具外，他還有其他很多的服務，像是 Proxy、Scraping Browser API、Web Scraper IDE、Web Unlocker 等等，如果有這方面的需求，也可以跟他們詢問 (反正問又不用錢XD)。

參考：
BrightData 官方網站
 BrightData SERP-API 官方文檔1
BrightData SERP-API 官方文檔2
BrightData SERP-API 常見 Q&A
BrightData 使用者後台

只做能力範圍的事，就永遠無法進步。

如何使用 Google 的 Gemini 模型 API？(基礎教學，附上 Python 範例程式)

jia@jiatool.com (Jia) — Sun, 17 Dec 2023 21:45:00 +0800

前言

在上個禮拜(12/6)推出了 Google DeepMind 開發的 Gemini (雙子星) ，是第一個在 MMLU (大規模多任務語言理解) 方面超越人類專家的模型，要與 OpenAI 的 GPT-4 來抗衡。

我之前寫過一篇如何使用 OpenAI ChatGPT API ，而在前幾天(12/13) Google 也開放了 Gemini Pro 版本的 API ，可以透過「Google AI Studio 中的 Gemini API」或「Google Cloud 的 Vertex AI 平臺」來存取。

Google DeepMind 開發的 Gemini 多模態模型

右邊有目錄，可直接跳至你想看的章節 →

Gemini 簡介

Gemini 是一個原生多模態的 LLM (大型語言模型)，從訓練時就餵進去文字、影像、音訊等等多種形態的資料，使用 Google 自行開發的 TPU 晶片訓練而成，是第一個在 MMLU (大規模多任務語言理解) 方面超越人類專家的模型。

* 官方 Gemini 簡介文章：https://blog.google/technology/ai/google-gemini-ai

而官方有釋出一部試用 Gemini Ultra 的展示影片，我看完真的覺得很驚訝，在網路上也掀起了一陣熱烈討論。

* 有 CC 中文字幕

* 有文章版可以看： How it's Made: Interacting with Gemini through multimodal prompting

* Gemini 的訓練資料是到 2023 年初，在此之後的它可能就不知道了。

Gemini 模型三種尺寸

Gemini 依照尺寸分成三種版本：

Gemini Ultra：最強大，適用高度複雜的任務
Gemini Pro：最通用
Gemini Nano：可於行動裝置上運作

目前 Google 的 Bard 背後已經換成了 Gemini Pro (好像只有英文版)，Gemini Nano 也應用於 Google Pixel 8 上。
而 Gemini Ultra 應該明年初會推出。

Gemini 分成三種尺寸

* Gemini Ultra 對比 OpenAI GPT-4；Gemini Pro 對比 OpenAI GPT-3.5。
* 目前只開放 Gemini Pro 版本的 API。

API 價格

以下價格都是 12/16 查詢的金額。

在明年初全面上市之前，可以 "免費" 使用相同速率限制、相同模型來嘗試，不確定之後還會不會有免費方案(但降低使用速率)。
* 免費方案的輸入輸出資料會被拿去訓練，需要注意。

Gemini Pro 的 API 限制每分鐘最多 60 個請求(以個人使用絕對夠用)，預計明年初之後收費如下：

Price (input)
$0.00025 / 1K characters
$0.0025 / image
Price (output)
$0.0005 / 1K characters

Gemini Pro 版本的 API 價格

而 OpenAI GPT 的 API 收費如下 (以 GPT-3.5 Turbo 為例)：

Price (input)
$0.001 / 1K tokens
Price (output)
$0.002 / 1K tokens

OpenAI GPT 的 API 價格

* 以上價格皆為美金，撰寫文章當下約 1 美金 = 31.3 新台幣。

比較一下，可以看到 Google 的 Gemini 相較來說更划算，便宜了 4 倍，而且注意看他們的計算方式也不同，一個是用 character、一個是用 token，我們來看看不同的計算方式差多少。

底下我自己實際用它們官網計算 token 的工具，來比較兩者的差距。

先測試一段英文，兩者算出來的 token 是差不多的 (分別為 24 跟 25)：

Gemini is built from the ground up for multimodality — reasoning seamlessly across image, video, audio, and code.

Google Gemini token 計算 - 英文

OpenAI GPT-3.5 token 計算 - 英文

但是，如果是中文，因為計算方式的差異，整整差了兩倍！！ (分別為 25 跟 50)

Gemini 是一個原生多模態的大型語言模型，在大規模多任務語言理解方面甚至超越人類專家。

Google Gemini token 計算 - 中文

OpenAI GPT-3.5 token 計算 - 中文

Gemini Pro API

創建 API key

進到 Google AI for Developers 的網站，可以查看 Google AI 模型的介紹、價格、說明文件與範例。

建置 Gemini

點擊 "Get API key in Google AI Studio" 前往 Google AI Studio 來在網頁上測試 LLM AI 模型(類似 Playground 頁面的用途) 與取得 API key，

建置 Gemini

Google AI Studio 是以瀏覽器為基礎的 IDE，可使用生成式模型進行原型設計。Google AI Studio 可讓您快速試用模型並嘗試各種提示建構符合需求的項目後，您可以從 Gemini API 提供支援的程式語言，並將其匯出為程式碼。

關於 Google AI Studio 的使用我就不多介紹了。提醒如果想輸入圖片，右邊的 Model 記得要切換成 Gemini Pro Vision，才有支援圖像。

* Google AI Studio 官方教學文章

Google AI Studio

點擊左邊的 "Get API key" > "Create API key in new project" 來自動產生一個 Google Cloud 專案並創建一個 API key。

創建 Google Cloud API key

Gemini 模型種類說明

Gemini models 種類說明列出目前可使用的 Gemini 模型資訊，包含 "模型說明"、"模型更新時間"、"輸入輸出類型"、"Token限制"、"頻率限制"

Gemini Pro 用在文字輸入，而 Gemini Pro Vision 可以文字加影像輸入。

Gemini 可使用的模型種類

API 版本說明

目前 Gemini API 有 v1 和 v1beta 版本：

v1：API 的穩定版。在主要版本的生命週期內，穩定版本的功能都能完整支援。如有任何破壞性變更，系統會建立 API 的下一個主要版本，並在合理的時間內淘汰現有版本。
v1beta：包含可能處於開發階段的搶先體驗功能，且需要快速更新及破壞性變更。請勿使用此版本於正式版應用程式。

API 版本比較 (v1 與 v1beta)

傳入參數

我們使用的 generateContent 方法其 Request 相關資訊如下：

POST https://generativelanguage.googleapis.com/v1/models/{gemini-pro or gemini-pro-vision}:generateContent?key={API_KEY}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


{
"contents": [
{
"parts": [
{
"text": "prompt..."
}
],
"role": "user or model"
}
],
"safetySettings": [
{
"category": "<enum (HarmCategory)>",
"threshold": "<enum (HarmBlockThreshold)>"
}
],
"generationConfig": {
"temperature": "<number>",
"topP": "<number>",
"topK": "<number>",
"candidateCount": "<integer>",
"maxOutputTokens": "<integer>",
"stopSequences": ["<string>"]
}
}

contents 放 prompt 提示 (text) 與角色 (role，可以是 user 或 model，不填則預設 user)。

safetySettings 是 OpenAI GPT 沒有的參數，用於封鎖不安全的回覆內容。

safetySettings > category 類別，可以使用以下數值：

數值	代表意思
HARM_CATEGORY_HARASSMENT	騷擾內容。
HARM_CATEGORY_HATE_SPEECH	仇恨言論和內容。
HARM_CATEGORY_SEXUALLY_EXPLICIT	情色露骨內容。
HARM_CATEGORY_DANGEROUS_CONTENT	危險內容。

* 其他還有 HARM_CATEGORY_UNSPECIFIED、HARM_CATEGORY_DEROGATORY、HARM_CATEGORY_TOXICITY、HARM_CATEGORY_VIOLENCE、HARM_CATEGORY_SEXUAL、HARM_CATEGORY_MEDICAL、HARM_CATEGORY_DANGEROUS，不過那是給 PaLM 2（舊版）模型使用的，Gemini 模型不支援。

safetySettings > threshold 封鎖門檻，可以使用以下數值：

數值	代表意思
HARM_BLOCK_THRESHOLD_UNSPECIFIED	未指定門檻。
BLOCK_LOW_AND_ABOVE	允許含有「NEGLIGIBLE」的內容
BLOCK_MEDIUM_AND_ABOVE	允許含有「NEGLIGIBLE」、「LOW」的內容。
BLOCK_ONLY_HIGH	允許含有「NEGLIGIBLE」、「LOW」、「MEDIUM」的內容。
BLOCK_NONE	允許所有內容。

generationConfig 用於設定模型生成和輸出的設定參數，其中幾個比較會用到的是：

temperature：輸出內容的隨機性。越接近 1.0，產生的回應會豐富、多元、更有創意；反之越接近 0.0，則會產生較有確定性、可能性較高的回覆。
maxOutputTokens：最大輸出回應 Token 數量。Gemini Pro 模型預設 2048；Gemini Pro Vision 模型預設 4096。
candidateCount：要傳回的回應數量。預設 1，可設定 1~8，但目前好像限制只能用 1。

用法可以直接看下一章節的 Python 範例程式碼。其他更詳細的說明，請參考以下官方文件：

回覆內容

API 範例回覆內容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


{
"candidates": [
{
"content": {
"parts": [
{
"text": "我知道王建民。王建民，1980年3月31日出生於台灣台中市，是一位前台灣棒球選手，司職投手。他曾效力於中華職棒的興農牛隊，美國職棒的紐約洋基隊、華盛頓國民隊和芝加哥白襪隊，以及中國棒球聯賽的北京猛虎隊。\n\n王建民是台灣史上第一位大聯盟先發勝投破百的投手，也是第一位入選大聯盟全明星賽的台灣選手。他在2006年締造19勝6敗、 防禦率3.63的優異成績，並在季後賽拿下3勝0敗的戰績，幫助洋基隊奪得世界大賽冠軍。王建民也因此成為台灣的棒球英雄，並獲得「台灣之光」的稱號。\n\n然而，王建民在2008年季初因傷缺陣，並在2009年進行了韌帶移植手術。此後，他的成績大幅下滑，並在2012年離開了大聯盟。王建民於2013年回歸中華職棒，效力於義大犀牛隊。2016年，他宣布正式退休。\n\n王建民的職業生涯戰績為127勝72敗， 防禦率3.92，三振數1718次。他是台灣棒球史上最成功的投手之一，也是台灣人民的驕傲。"
}
],
"role": "model"
},
"finishReason": "STOP",
"index": 0,
"safetyRatings": [
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_HARASSMENT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"probability": "NEGLIGIBLE"
}
]
}
],
"promptFeedback": {
"safetyRatings": [
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_HARASSMENT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"probability": "NEGLIGIBLE"
}
]
}
}

candidates 就是回應候選內容，目前好像只會有一個，因為輸入的 generationConfig > candidateCount 它也只讓我設定 1。

content：生成回應內容，格式跟輸入的 contents 一樣。
finishReason：模型停止產生 token 的原因。

數值	代表意思
FINISH_REASON_UNSPECIFIED	預設值。這個值未使用。
STOP	模型的自然停止或提供的停止序列。
MAX_TOKENS	已達到請求中指定的 token 數量上限。
SAFETY	內容因安全原因而被標記。
RECITATION	內容因遭檢舉為引用原因而被標記。
OTHER	未知原因。

index：此候選內容在候選清單中的索引 (目前只有一則)。
safetyRatings：安全性評級清單。顯示此回覆內容在各項安全性類別的等級(可能性)。

我自己在測試時，有時會如下回應，不知道是不是剛推出，所以還不太穩。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
"candidates": [{"finishReason": "OTHER", "index": 0}],
"promptFeedback": {
"safetyRatings": [
{"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE"},
{"category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE"},
{"category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE"},
{"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE"}
]
}
}

其他更詳細的說明，請參考以下官方文件：

Gemini API GenerateContentResponse 參考資料

Python 範例程式碼

在官網的範例是使用他們創建的 google-generativeai 套件。
不過這邊我想改用我們熟悉的 Requests 套件來嘗試、示範。

首先要確認有安裝 Requests 套件：

1

pip install requests

那我們開始吧~🏃

單個純文字

純粹問它一段話：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 單個純文字
import json
import requests
url = f'https://generativelanguage.googleapis.com/v1/models/gemini-pro:generateContent?key={API_KEY}'
headers = {'Content-Type': 'application/json'}
data = {
"contents": [
{
"parts": [{"text": "你知道王建民嗎？"}]
}
]
}
response = requests.post(url, headers=headers, json=data)
print(f"response status_code: {response.status_code}")
print(json.dumps(response.json(), indent=4, ensure_ascii=False))

單個純文字 + 參數

問它一段話，並且加上一些參數設定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# 單個純文字 + 參數
import json
import requests
url = f'https://generativelanguage.googleapis.com/v1/models/gemini-pro:generateContent?key={API_KEY}'
headers = {'Content-Type': 'application/json'}
data = {
"contents": [
{
"parts": [{"text": "你知道王建民嗎？"}]
}
],
"safetySettings": [
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"threshold": "BLOCK_NONE"
}
],
"generationConfig": {
"temperature": 1.0,
"maxOutputTokens": 30,
"topP": 0.8,
"topK": 10
}
}
response = requests.post(url, headers=headers, json=data)
print(f"response status_code: {response.status_code}")
print(json.dumps(response.json(), indent=4, ensure_ascii=False))

多輪純文字對話（聊天）

像在 Bard 或 ChatGPT 上一樣，可以多輪對話，它會記得之前的內容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


# 多輪對話（聊天）
import json
import requests
url = f'https://generativelanguage.googleapis.com/v1/models/gemini-pro:generateContent?key={API_KEY}'
headers = {'Content-Type': 'application/json'}
data = {
"contents": [
{
"role": "user",
"parts": [{"text": "你知道王建民嗎？"}]
},
{
"role": "model",
"parts": [{"text": "我知道王建民。王建民，1980年3月31日出生於台灣台中市，是一位前台灣棒球選手，司職投手。他曾效力於中華職棒的興農牛隊，美國職棒的紐約洋基隊、華盛頓國民隊和芝加哥白襪隊，以及中國棒球聯賽的北京猛虎隊。\n\n王建民是台灣史上第一位大聯盟先發勝投破百的投手，也是第一位入選大聯盟全明星賽的台灣選手。他在2006年締造19勝6敗、 防禦率3.63的優異成績，並在季後賽拿下3勝0敗的戰績，幫助洋基隊奪得世界大賽冠軍。王建民也因此成為台灣的棒球英雄，並獲得「台灣之光」的稱號。\n\n然而，王建民在2008年季初因傷缺陣，並在2009年進行了韌帶移植手術。此後，他的成績大幅下滑，並在2012年離開了大聯盟。王建民於2013年回歸中華職棒，效力於義大犀牛隊。2016年，他宣布正式退休。\n\n王建民的職業生涯戰績為127勝72敗， 防禦率3.92，三振數1718次。他是台灣棒球史上最成功的投手之一，也是台灣人民的驕傲。"}]
},
{
"role": "user",
"parts": [{"text": "他現在在哪裡？"}]
},
]
}
response = requests.post(url, headers=headers, json=data)
print(f"response status_code: {response.status_code}")
print(json.dumps(response.json(), indent=4, ensure_ascii=False))

單個文字和圖片

如果需要 AI 可以看圖片，需要改用 Gemini Pro Vision 模型 (支援文字和圖片輸入)，並且圖片要轉換為 Base64 編碼的字串，

圖片的 mime_type 參數目前支援「image/png」、「image/jpeg」、「image/heic」、「image/heif」、「image/webp」幾種格式。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# 單個文字和圖片
import json
import requests
import base64
# 讀取圖片檔案，並轉換成 Base64 編碼的字串
with open("gemini_test_image.jpg", "rb") as image_file:
image_base64_string = base64.b64encode(image_file.read()).decode('utf-8')
# print(image_base64_string)
url = f'https://generativelanguage.googleapis.com/v1/models/gemini-pro-vision:generateContent?key={API_KEY}'
headers = {'Content-Type': 'application/json'}
data = {
"contents": [
{
"parts": [
{"text": "詳細說明你在這張圖片中看到什麼？"},
{
"inline_data": {
"mime_type": "image/jpeg",
"data": image_base64_string
}
}
]
},
]
}
response = requests.post(url, headers=headers, json=data)
print(f"response status_code: {response.status_code}")
print(json.dumps(response.json(), indent=4, ensure_ascii=False))

結語

v1 Beta 版本還有更多功能，像是函數呼叫(Function calling) 、語意檢索器(Semantic Retriever、RAG) ，雖然還在測試中，不建議用於正式版應用，但有興趣的還是可以去玩玩看🤖。

至少在今年底前使用 Google Gemini API 都是「免費」使用，你想要拿來練習、做專案、做 Side Project 都可以使盡玩(?)，但要注意不要上傳任何敏感資料，因為目前方案所有的輸入輸出都可能會被拿去當訓練資料。

參考：
Google Gemini 官方網站
 Google Gemini API 說明文件
 Google AI Studio
Google for Developers Blog

The sky’s the limit
一切皆有可能

DataForSEO 教學 — Google、Yahoo 搜尋結果 SERP API

jia@jiatool.com (Jia) — Sat, 18 Nov 2023 21:50:00 +0800

(先澄清，以下非業配，純粹依個人使用過程描述。)

前言

在很久之前，我有寫一篇關於第三方 Google 搜尋結果的 API (Aves API) 。而最近又在因緣際會下，被迫(?)接觸了另一個類似的服務平台 — DataForSEO。

DataForSEO 提供了更多的服務，包括 Google Search、Google Maps、Google News、Google Images、YouTube、Yahoo Search、Bing Search、百度 Search、Google Play 和 Apple App，還有一些其他商業應用的服務。可以看的出來還蠻多樣的，如果有這方面的需求或許可以參考。

這次就改以「Yahoo 搜尋 API」當範例，來跟著我一起嘗試這個 API 服務吧，這篇也算把我自己的使用經驗記錄下來。

DataForSEO 官網

SERP API

官方的 SERP API 頁面有一些簡單的介紹，SERP API 目前支援以下幾種搜尋：

Google SERP
Google 圖片
Google 新聞
Google 地圖
Yahoo SERP
Bing SERP
百度 SERP
YouTube SERP

SERP API 支援的搜尋引擎

搜尋測試頁面

在 DataForSEO 官網上有提供一個 Google SERP 搜尋測試頁面，可以實際輸入關鍵字，並查看它回傳的資料，只可惜好像沒有提供台灣的選項。

但它在使用者後台(需註冊)也有提供一個 API Explorer (就是 Playground) 的 GUI 介面，會完整許多，各種支援的搜尋引擎都可以選，地區也有台灣(並細分到縣市)，也有許多參數可以設定，但這邊就會直接花到錢的 (新帳戶有送 1 美元的額度可供試用)。

關於使用者後台頁面，我文章後續章節會再介紹。

Google SERP 搜尋測試頁面

SERP API 價格

搜尋 API 價格官方有詳細說明在這個網頁，依照你使用的模式它分為三種價格：STANDARD QUEUE、PRIORITY QUEUE、LIVE MODE。

STANDARD QUEUE：每一次查詢 $0.0006，平均等 5 分鐘。
PRIORITY QUEUE：每一次查詢 $0.0012，平均等 1 分鐘。
LIVE MODE：每一次查詢 $0.002，平均等 6 秒。

* 以上價格為美金

SERP API 價格

LIVE MODE 使用上最簡單，只要單一請求就會回傳結果，速度也最快，但價格當然也最貴。
STANDARD QUEUE 和 PRIORITY QUEUE 則是要先發送查詢任務請求，再來定時去問問它查好了沒，最後再取得查詢結果，要分成三段，在程式上寫起來比較麻煩，但它比較便宜(窮人的悲哀QQ)，而 STANDARD QUEUE 和 PRIORITY QUEUE 兩者看起來只差在等待時間及價格。

以下文章我會以 STANDARD QUEUE 和 PRIORITY QUEUE 模式來示範。

API 使用

SERP API 使用上分為三個請求：

Task POST (task_post)：設定任務
Tasks Ready (tasks_ready)：取得已完成任務
Task GET (task_get)：取得任務的結果

* STANDARD QUEUE、PRIORITY QUEUE 模式的區分是在送出 task_post 請求時，帶上 priority 參數來指定，1 (預設)代表 STANDARD、2 代表 PRIORITY。

SERP API 流程

首先使用 "Task POST" 設定查詢任務，指定關鍵字以及其餘參數，讓它開始去抓我們想要的搜尋結果，這邊最多可以一次給 100 組關鍵字，不過稍微注意有限制每分鐘最多只能發送 2000 個 API 請求。

* 你也可以指定 pingback_url，當任務完成時它會主動通知你；
* 或指定 postback_url，當任務完成時它會主動將結果傳送給你。
再來使用 "Tasks Ready" 查詢它執行完哪些任務，可以每 10 秒檢查一次，或一分鐘檢查一次，它只有限制每分鐘最多進行 20 次 API 請求。另外，已經被收集的任務(我猜是指已使用 task_get 取得的任務)和放超過三天未收集的任務會被移除不會在裡面。
最後，使用 "Task GET" 帶上任務 ID 取得任務的查詢結果，它有分三種 Regular、Advanced、HTML，Regular 就是以 JSON 格式整理好的結果；Advanced 跟 Regular 一樣，只是好像還有多一些特定資訊，我也不是很清楚；HTML 就是回傳搜尋結果的 HTML 格式。

* 而且任務結果在 30 天內都會保留，用 ID 都可以取得結果。
* 關於搜尋結果不同類別(type)各自代表甚麼，在這邊有官方的圖文說明：https://dataforseo.com/serp-features

* 以上三種請求，只有 "Task POST" 會收費，其餘兩個並不會產生費用。

送出的請求 Header 皆需要帶上憑證，確認是哪個帳號發出的，其格式如下：

Authorization: Basic ${credentials}

其中 credentials 是將你的 "API login" 與 "API password" 組的字串 {login}:{password} 經過 Base64 編碼的結果。

例如帳號是 jia@gmail.com、密碼是 abc123，組成 jia@gmail.com:abc123，再經過 Base64 變成 amlhQGdtYWlsLmNvbTphYmMxMjM=。

* "API login" 與 "API password" 可以在使用者後台 API Dashboard 網頁找到。

對了，
它們 API 還有提供 📦 沙盒模式(Sandbox)，讓我們可以在撰寫程式時做測試，不會花費到費用，但當然回傳的資料就是它們的範例資料，但可以讓我們確認 API 回傳的資料格式、測試程式有沒有問題。

官方文件：https://docs.dataforseo.com/v3/appendix/sandbox/

* 官方文件有更完整的說明：https://docs.dataforseo.com/v3/serp/yahoo/overview/

* 其他常見的 Q&A：https://dataforseo.com/help-center/category/serp-api

Python 範例

首先要確認有安裝 Requests 套件：

1

pip install requests

完整 Python 程式碼：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79


import json
import requests
class DataforseoSerp():
def __init__(self, credentials, open_sandbox=False):
self.base_url = 'https://api.dataforseo.com/v3/serp'
if open_sandbox:
self.base_url = 'https://sandbox.dataforseo.com/v3/serp' # 沙盒模式
self.search_engine = 'yahoo'
self.headers = {
'Authorization': f'Basic ${credentials}',
'Content-Type': 'application/json',
}
self.location_code = 1012825 # New Taipei City,Taiwan
# https://docs.dataforseo.com/v3/serp/yahoo/locations/
self.language_code = 'zh-TW'
# https://docs.dataforseo.com/v3/serp/yahoo/languages/
self.device = "desktop" # mobile
self.os = "windows" # macos android ios
def task_post(self, keywords, depth=100):
"""
 設定查詢任務，keywords 最多一次可以 100 個，每分鐘最多可以發送 2000 個 API 呼叫
 https://docs.dataforseo.com/v3/serp/yahoo/organic/task_post/
 """
if (keywords is None) or (len(keywords) == 0):
return None
url = f'{self.base_url}/{self.search_engine}/organic/task_post'
data = []
for keyword in keywords:
data.append({
"keyword": keyword,
"location_code": self.location_code,
"language_code": self.language_code,
"device": self.device,
"os": self.os,
"depth": depth
})
response = requests.post(url, headers=self.headers, json=data)
return response.json()
def tasks_ready(self):
"""
 取得已完成的查詢任務
 https://docs.dataforseo.com/v3/serp/yahoo/organic/tasks_ready/
 """
url = f'{self.base_url}/{self.search_engine}/organic/tasks_ready'
response = requests.get(url, headers=self.headers)
return response.json()
def task_get(self, task_id):
"""
 取得查詢任務的結果
 https://docs.dataforseo.com/v3/serp/yahoo/organic/task_get/regular/
 """
if task_id is None:
return None
url = f'{self.base_url}/{self.search_engine}/organic/task_get/regular/{task_id}'
response = requests.get(url, headers=self.headers)
return response.json()
if __name__ == "__main__":
dataforseo_serp = DataforseoSerp("xxxxxxxxxxxxxxxxxxxxxxxxxxx", open_sandbox=True)
result = dataforseo_serp.task_post(["飲料"])
print(json.dumps(result))
result = dataforseo_serp.tasks_ready()
print(json.dumps(result))
result = dataforseo_serp.task_get("11171539-6790-0066-2000-fa82270464a2")
print(json.dumps(result))
with open('dataforseo_serp_result.json', 'w') as f:
json.dump(result, f)

當然比較好的做法，是還要判斷它回傳結果的 status_code 欄位和 tasks 底下的 status_code 欄位，確保任務執行 OK 才去取資料，如果有錯誤，程式內要做相對應處理。

這邊只是為了示範，我就沒有寫出來了。

* 各個狀態代碼意思如這個官方清單。

使用者後台

當註冊後登入，即可進入使用者後台頁面去查看更多相關資訊。

其中有幾個重要的頁面：

API Dashboard (儀錶板)
API Usage (使用紀錄)
API Errors (錯誤紀錄)
API Explorer (API Playground)
API Settings (設定 API 限制)

API Dashboard (儀錶板)

有顯示你的 "API login" 與 "API password"，以及圖表化顯示每天的花費。

API Dashboard (儀錶板) 頁面

API Usage (使用紀錄)

就是你 API 的呼叫紀錄，它有將不同種類的 API 區分開來，方便我們查找。
有紀錄任務 ID、執行時間、執行狀態、花費、送出的參數，甚至可以從這邊看到查詢結果(等同於 "Task GET" 請求)。

API Usage (使用紀錄) 頁面

API Errors (錯誤紀錄)

發生錯誤的 API 請求會在這頁列出來。

API Errors (錯誤紀錄) 頁面

API Explorer (API Playground)

以圖形化的操作頁面，讓你實際測試 API 的結果是否符合你的預期，有輸入框讓你設定 API 不同參數，像是用哪個搜尋引擎、地區(有細分到縣市)、語言、電腦版或手機版、作業系統、關鍵字。

但要稍微注意，這邊是會直接花到錢的 (新帳戶有送 1 美元的額度可供試用)。

API Explorer (API Playground) 頁面

API Settings (設定 API 限制)

能設定可以呼叫 API 的 IP 白名單、限制每日最大花費額度(總共額度，或也可以細到 by 不同 API 去限制)。

API Settings (設定 API 限制) 頁面

注意事項

我在使用 Yahoo 搜尋 API 時發現，我明明設定要 100 筆結果(depth=100)，結果回傳只有 70 筆、甚至 40 幾筆而已的，我也有透過 API 回傳的 check_url 網址去確認，經過詢問與確認，官方是這樣答覆我：

Today, you contacted our Support Team and provided us with ID of your task sent to the Yahoo Serp API that returned fewer results than expected.
Our developers have carefully checked the situation and explained that such a search engine has some limitations. To avoid timeouts, we have a restriction that allows us to crawl up to 6 pages of the ordinary SERP (the one you can see in a browser). Taking into account that each page contains 7-8 results. In total, the API does not return more than 50 results.
If we remove such a restriction globally, this API will return 500 errors, and since we will have to send numerous requests to this search engine, it may harm it due to high traffic coming from us. I hope it makes sense.
Hope for your understanding!

也就是可能他們的 Yahoo 搜尋 API 很可能沒辦法抓到我們指定的筆數，除非你只需要第一頁，或前三頁之類的，不然這也是很困擾，要特別注意。

結語

相比上次使用的 Aves API 來說，DataForSEO 真的多了非常多的服務，而且價格貌似也比較便宜。官方同樣有線上客服，有相關需求都可以直接詢問，回應速度還蠻快的。

當然我目前只是短暫的嘗試，還不確定它長久、大量地使用下來穩定性如何，這部分有需求的人可以自行比較看看。

參考：
DataForSEO 官方網站
 DataForSEO 官方文檔
 DataForSEO Dashboard 後台

「失敗很正常，如果沒有經歷失敗，表示你還不夠創新。」
Failure is an option here. If things are not failing, you are not innovating enough.

—— Elon Musk 伊隆·馬斯克 (著名企業家)

OpenAI ChatGPT API 如何使用？(附上 Python 範例程式)

jia@jiatool.com (Jia) — Sat, 18 Mar 2023 21:10:00 +0800

前言

ChatGPT 是由 OpenAI 所開發的一個基於 GPT-3.5 架構的大型語言模型，自從去年底發表到現在依然話題不斷、人氣超高。而在三月初，OpenAI 公開了 ChatGPT 的 API，也就是 gpt-3.5-turbo 模型的 API，讓我們不再被限制只能透過官方網頁使用，並且提供更多可調整的參數選項。

這篇文章就是要一起來了解 ChatGPT API，並實際使用 Python 串接 API (當然有 Python 範例程式碼)，帶著大家快速上手。

這兩份官方文件建議可以看看：

OpenAI 公開 ChatGPT API

API key 申請

進到帳號的 API key 頁面，登入帳號後，點擊 “Create new secret key” 來產生 API key，這時候就要把 key 複製並保存下來了，如果忘記的話，再產生一次即可。

API key 申請

使用量與計費方式

而帳號實際的總使用量可以到帳號 Usage 頁面查看。

目前每個帳號會贈送 18 美元的額度讓你試用 (如果你是用同一組手機去開多個帳號，那就不一定了)，並且有使用期限要留意，不要白白浪費了~
如果免費額度用完過到期，就應該要綁信用卡才能使用了。

每種模型的計費方式可參考官網 Pricing 頁面說明。

帳號實際的總使用量

範例程式碼

馬上給各位看看範例程式碼。

這邊分別使用使用兩種套件來示範，我們之前常用的 requests，與官方提供的 openai 套件。

Model 使用 ChatGPT 的 gpt-3.5-turbo，如果之後 GPT-4 的也開放後可以使用 gpt-4。
目前 OpenAI API 有提供這些 Model ，裡面有對每一種 Model 做詳細說明。

使用 requests 套件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


import requests
API_KEY = '<YOUR_API_KEY>'
response = requests.post(
'https://api.openai.com/v1/chat/completions',
headers={
'Content-Type': 'application/json',
'Authorization': f'Bearer {API_KEY}'
},
json={
'model': 'gpt-3.5-turbo',
'messages': [{"role": "user", "content": "說句話吧"}],
}
)
print(response.json())

使用官方 openai 套件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


import openai
openai.api_key = '<YOUR_API_KEY>'
completion = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[
{"role": "user", "content": "說句話吧"}
]
)
print(completion)

參數

輸入參數除了上方範例中的 model 和 messages，還有以下這些。

此表格是依照官方 API Reference 所整理出來的。

參數名稱	資料型態	必填/選填	預設值	說明
`model`	string	必填	-	要使用的 Model ID。 ( 可使用的model )
`messages`	array	必填	-	以對話格式生成對話的訊息。 ( 格式參考，或以下說明)
`temperature`	number	選填	1	介於 0 和 2 之間。較高的值(如 0.8)將使輸出更加隨機，而較低的值(如 0.2)將使輸出更加集中和確定。
`top_p`	number	選填	1	一種替代`temperature`的方法(nucleus sampling)。Model 考慮具有 top_p 概率質量的標記的結果。所以 0.1 意味著只考慮構成前 10% 概率質量的標記。
`n`	integer	選填	1	輸出幾種回覆結果。 (參考以下說明)
`stream`	boolean	選填	false	開啟 stream 方式傳送，就像 ChatGPT 網頁版那樣會一個一個字跑出來。( 官方範例 )
`stop`	string or array	選填	null	指定字串，如果回覆有出現這些字串將會停止輸出。
`max_tokens`	integer	選填	inf	聊天完成時生成的最大令牌數。如果太小它可能回覆到一半就會斷掉，但每種 Model 都有各自的最大值。
`presence_penalty`	number	選填	0	-2.0 和 2.0 之間的數字。正值會根據到目前為止是否出現在文本中來懲罰新標記，從而增加 Model 談論新主題的可能性。
`frequency_penalty`	number	選填	0	-2.0 和 2.0 之間的數字。正值會根據新標記在文本中的現有頻率對其進行懲罰，從而降低 Model 逐字重複同一行的可能性。
`logit_bias`	map	選填	null	修改指定標記出現在完成中的可能性。
`user`	string	選填	-	代表你的用戶的ID，幫助 OpenAI 監控和檢測濫用行為。 ( 更多說明 )

* 官方建議不要同時更改 temperature 和 top_p，可以參考這邊的說明。

* 表格內有幾個說明你可能看不懂，因為我也不太懂 XP

messages 是個陣列的格式，放著你們之間的對話。
裡面的 role 欄位可以放三種身分：“system”、“user”、“assistant”。

對話可以先有一則 “system”，對 Model 先做出指示，例如 “你是一隻貓” (？，不過官方說 gpt-3.5-turbo 對 “system” 消息的關注度不高，因此重要的說明建議還是放在 “user” 的消息比較好。
“user” 是我們使用者的發問；“assistant” 則是 Model 的回話。

如果你想要讓對話有上下文關係(要讓 Model 記得之前講過的話)，要把全部對話紀錄都在傳給它，然後這些都算進 token(使用量) 裡…，像是底下這樣。

第一次問它：

1
2
3


"messages": [
{"role": "user", "content": "王建民是誰"}
]

它回覆：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


"usage": {
"prompt_tokens": 14,
"completion_tokens": 217,
"total_tokens": 231
},
"choices": [
{
"message": {
"role": "assistant",
"content": "\n\n王建民是一位台灣籍棒球運動員，曾效力於美國職棒大聯盟紐約洋基隊、匹茲堡海盜隊、倫敦青年隊、堪薩斯城皇家隊等隊伍，擅長投球，被譽為是台灣最優秀的投手之一。他在職業生涯期間獲得多項獎項，包括台灣大賽MVP、亞洲聯盟MVP、美國聯盟先發投手等。他在2015年正式宣布退役，現在是一位棒球分析師和教練。"
}
}
]

想再繼續深入詢問，第二次問它，就要把剛剛我問的跟他回的都放進去：

1
2
3
4
5


'messages': [
{"role": "user", "content": "王建民是誰"},
{"role": "assistant", "content": "\n\n王建民是一位台灣籍棒球運動員，曾效力於美國職棒大聯盟紐約洋基隊、匹茲堡海盜隊、倫敦青年隊、堪薩斯城皇家隊等隊伍，擅長投球，被譽為是台灣最優秀的投手之一。他在職業生涯期間獲得多項獎項，包括台灣大賽MVP、亞洲聯盟MVP、美國聯盟先發投手等。他在2015年正式宣布退役，現在是一位棒球分析師和教練。"},
{"role": "user", "content": "他在美國大聯盟最多一年曾經拿過幾勝"},
]

它回覆：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


"usage": {
"prompt_tokens": 268,
"completion_tokens": 63,
"total_tokens": 331
},
"choices": [
{
"message": {
"role": "assistant",
"content": "王建民在美國大聯盟生涯中最多一年的勝場數為19勝，是在2008年效力於倫敦青年隊時所取得的成績。"
}
}
]

可以感受到 total_tokens 的使用量了嗎？
如果想讓它記得以前講過的話，每次請求所消耗的 token 是要繼續往上疊的，也是蠻恐怖的 XD

以上內容可以參考官方說明。

參數 n 是代表你想要它給出幾種回覆，例如 n=3 會產生如下三則訊息回覆：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


"choices": [
{
"message": {
"role": "assistant",
"content": "\n\n你好，有什麼我可以幫助您的？"
},
"finish_reason": "stop",
"index": 0
},
{
"message": {
"role": "assistant",
"content": "\n\n您好，有什麼我能幫助您的嗎？"
},
"finish_reason": "stop",
"index": 1
},
{
"message": {
"role": "assistant",
"content": "\n\n您好，有什麼我可以為您做的嗎？"
},
"finish_reason": "stop",
"index": 2
}
]

回覆內容

依照上方的範例程式，他回傳的格式與內容會類似這樣：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


{
"id": "chatcmpl-6v4faabcd9gXfUerJvBf123Co",
"object": "chat.completion",
"created": 1679060660,
"model": "gpt-3.5-turbo-0301",
"usage": {
"prompt_tokens": 14,
"completion_tokens": 24,
"total_tokens": 38
},
"choices": [
{
"message": {
"role": "assistant",
"content": "\n\n你好，有什麼我可以為你效勞的嗎？"
},
"finish_reason": "stop",
"index": 0
}
]
}

usage 欄位顯示你本次消耗的 token 數量。

prompt_tokens：你問他(輸入)所消耗的 token。
completion_tokens：它回覆(輸出)所消耗的 token。
total_tokens：本次請求總共消耗多少 token，也就是 prompt_tokens 加 completion_tokens。

如果想知道一句話代表幾個 token，可以使用官方提供的 Python 套件 — tiktoken：https://github.com/openai/tiktoken
也有計算 token 相關的使用說明。

本來想說可以使用官方的 Tokenizer 網頁來計算，但它是 GPT-3 Model 的，官方有說轉換 token 的計算方式可能因不同 Model 而異，因此我實際使用其實跟 gpt-3.5-turbo 出來的結果有落差。

帳號實際的總使用量可以到帳號 Usage 頁面查看。

* 你會發現中文消耗的 token 比英文還多很多😭

choices 內就是主要我們想知道的部分 — ChatGPT 的回覆。

message > content：回覆的內容。
index：代表第幾種回覆。(如果輸入參數有設定 n 的話)
finish_reason：代表此次回覆結束的原因(狀態)，可能會有以下四種值：
- stop：完整的輸出。
- length：由於 max_tokens 參數或 token 限制，導致輸出不完整。
- content_filter：由於內容過濾器中的標誌而省略了內容。
- null：API 響應仍在進行中或未完成。

Playground 遊樂場

OpenAI 還有提供 Playground 遊樂場，可以在上面測試不同的模型、調整不同的參數，觀察其結果，方便我們去快速了解。

Playground 遊樂場：https://platform.openai.com/playground

Playground 遊樂場

對了，使用 Playground 也是會消耗你自己的 token，這點要稍微注意一下，不要以為是 ChatGPT 網頁而玩過頭了🤣

其他說明

串接 OpenAI API 發出請求可能會收到錯誤，而完整詳細的錯誤代碼說明與進一步的解決辦法，可以參考這邊官方的文章：https://platform.openai.com/docs/guides/error-codes

OpenAI API 在使用上還有一些速率限制，如果使用會比較大量的朋友可以過去了解一下：https://platform.openai.com/docs/guides/rate-limits/overview

結語

使用 OpenAI API 上非常簡單，只是有些小地方要注意一下。
在看完以上介紹，趕快實際動手做，看看有沒有什麼 idea 可以進一步放大 ChatGPT 的用途~

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
OpenAI 官方說明文件
 OpenAI 官方 API 參考
 OpenAI 帳號後台
 OpenAI 各種 Model 說明
 OpenAI 各種 Model 價格
 OpenAI Playground 遊樂場
 OpenAI API 錯誤代碼
 OpenAI API 速率限制

別讓沒有夢想的人摧毀你的夢想。

「TDX 運輸資料流通服務平台」Google Apps Script 範例，PTX 平台的升級版~

jia@jiatool.com (Jia) — Fri, 30 Dec 2022 21:00:00 +0800

前言

先預祝 2023 元旦快樂~🎉🎉🎉 恭喜各位又老一歲了(?

之前介紹的「 PTX 公共運輸資訊平台」已經確定在今年 2022/12/01 正式落日，所以後來我有寫一篇將取代 PTX 平台的「TDX 運輸資訊整合流通服務平台」介紹，並示範如何使用 Python 來串接。

PTX 平台關閉

因為剛好有網友詢問，所以本篇也會使用 Google Apps Script 來取得 TDX 的交通資料，兩者在 API 認證授權機制差異不小。
關於 TDX 平台的介紹、如何註冊並取得API金鑰等資訊之前這篇文章都講解過了，這篇我們就直接進入 Google Apps Script 程式主題。

TDX 運輸資訊整合流通服務平台

取得API金鑰

TDX 平臺現階段開放每位會員最多建立三把API金鑰，每把API金鑰由一組 Client Id 和 Client Secret 所組成。

每個呼叫來源端 IP 呼叫次數限制為 50 次/秒。

TDX 平臺 API 採 OIDC Client Credential 機制進行身分驗證，程式介接範例可參考範例程式碼。

登入 TDX 平台後，前往會員中心 > (左邊) > 資料服務 > API金鑰頁面，點擊 "編輯" 即可查看 "Client Id" 和 "Client Secret"，將這兩組字串記錄下來，call API 時需要帶上。

API金鑰頁面

有關 API 金鑰服務使用流程說明，請參考官方說明。

API 認證授權機制

詳細步驟說明如下:

取得 Access Token

依照以下格式發出請求：

Request URL: https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token
Request Method: POST
Request Headers:
content-type: application/x-www-form-urlencoded
data:
grant_type: client_credentials
client_id: <your_client_id>
client_secret: <your_client_secret>

data 參數說明如下:

Key	Value
`grant_type`	固定使用 `client_credentials`
`client_id`	您的 Client Id，從 TDX 會員中心取得
`client_secret`	您的 Client Secret，從 TDX 會員中心取得

回傳資料是 JSON 格式，其中包含 access_token 參數，就是我們要的 Access Token。

對應的 Google Apps Script code：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


function GetAuthorizationToken() {
var token_url = "https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token";
var options = {
"method": "post",
"headers": {
"content-type": "application/x-www-form-urlencoded"
},
"payload": {
"grant_type": "client_credentials",
"client_id": '<YOUR CLIENT ID>',
"client_secret": '<YOUR CLIENT SECRET>'
}
};
var response = UrlFetchApp.fetch(token_url, options);
outData = JSON.parse(response.getContentText());
// console.log(outData);
 return outData['access_token'];
}

呼叫 TDX API 服務，取得數據資料

Request URL: TDX_API_URI
Request Method: GET
Request Headers:
authorization: Bearer <Access_Token>

* 若 Access Token 時間超過有效期限(第一步驟收到回應中的 expires_in 參數)，則再重新透過第一步驟取得即可。

對應的 Google Apps Script code：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


function doGet(e) {
var url = 'https://tdx.transportdata.tw/api/basic/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON'
var options = {
"method": "get",
"headers": { "authorization": "Bearer " + GetAuthorizationToken() }
};
var response = UrlFetchApp.fetch(url, options);
// console.log(response.getResponseCode());
 var outData = JSON.parse(response.getContentText());
console.log(outData);
return ContentService.createTextOutput(JSON.stringify(outData)).setMimeType(ContentService.MimeType.JSON);
}

* 官方的說明文件： https://github.com/tdxmotc/SampleCode

完整 Google Apps Script 程式範例

以同樣條件當範例查詢：台鐵"台北"車站即時的列車到離站看板資訊，並且只要"逆行"的列車

查詢的 URL 會長得像這樣：
https://tdx.transportdata.tw/api/basic/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


var CLIENT_ID = '<YOUR CLIENT ID>';
var CLIENT_SECRET = '<YOUR CLIENT SECRET>';
function doGet(e) {
var url = 'https://tdx.transportdata.tw/api/basic/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON'
var options = {
"method": "get",
"headers": { "authorization": "Bearer " + GetAuthorizationToken() }
};
var response = UrlFetchApp.fetch(url, options);
// console.log(response.getResponseCode());
 var outData = JSON.parse(response.getContentText());
console.log(outData);
return ContentService.createTextOutput(JSON.stringify(outData)).setMimeType(ContentService.MimeType.JSON);
}
function GetAuthorizationToken() {
var token_url = "https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token";
var options = {
"method": "post",
"headers": {
"content-type": "application/x-www-form-urlencoded"
},
"payload": {
"grant_type": "client_credentials",
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET
}
};
var response = UrlFetchApp.fetch(token_url, options);
outData = JSON.parse(response.getContentText());
// console.log(outData);
 return outData['access_token'];
}

透過上方的 "執行" 確認沒問題後，可參考這篇的教學將程式部署起來。

其他程式範例

除了參考我上面的 Google Apps Script 範例，與我上次整理的 Python 教學，TDX 官方有提供 C#、JavaScript、Java、PHP、R 程式語言的範例程式碼，需要的可前往參考 ( GitHub )。

結語

如果你想做的應用需要「公共運輸」相關資料，那應該就是串接 TDX 平台，資料齊全、方便很多~

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
TDX 運輸資料流通服務平台 | 官網
 TDX API 說明 | Swagger 文件工具
 TDX 官方介接說明與範例程式碼 | GitHub
TDX 平台常見問題 | 官網

與其埋怨暗路，不如自己點燈。

「TDX 運輸資料流通服務平台」含 Python 範例程式，PTX 平台的升級版~

jia@jiatool.com (Jia) — Sun, 19 Jun 2022 21:25:00 +0800

前言

在之前文章介紹 PTX 公共運輸整合資訊流通服務平台，它整合多項公共運輸的資料服務 API，供我們串接取得相關數據。

但經網友提醒，才發現 PTX 竟然只服務到今年(2022年)底，之後會改以「TDX 運輸資訊整合流通服務平台」代替，因此本篇文章將帶大家快速了解一下 TDX 平台，以及實際使用 Python 來串接，取得相關數據資料。

PTX 平台關閉

後來我有寫一篇 Google Apps Script 範例程式可以參考哦~

TDX 運輸資訊整合流通服務平台

TDX 平台說明

按照官網的說法，TDX 整合交通部運輸數據五大平台(PTX、Traffic、GIS-T、TICP、LINK)，並使用全新的認證授權方式管控資源存取權限，提供單一服務查詢與介接入口。短時間內五大平台與 TDX 平台將持續並行運作，但未來會以 TDX 為主要的數據流通平台。
(參考： TDX 平台常見問題 )

TDX 整合五大平台 (圖片來源：TDX官網)

實際使用其實「TDX 運輸資訊整合流通服務平台」服務及概念是跟「PTX 公共運輸整合資訊流通服務平台」差不多的，只是相較於 PTX 平台，TDX 平台又多了許多種類的資料，像是 "即時路況"、"停車資訊"、"GIS圖資"、"道路編碼" 等等也把它整合進來。

TDX 平台服務範疇

TDX 平台也有個詳細各項服務查詢頁面，可依照 "服務類型"、"資料主題"、"領域類型"、"資料類型" 來做篩選。

TDX 各項服務查詢

註冊會員 & 取得API金鑰

同樣為了系統資源使用之公平性與資通訊安全考量，要先註冊會員來取得 API 金鑰( TDX 註冊頁面 )，但不知道是不是因為平台還在試營運階段的關係，審核完成並沒有寄 Email 通知，是我主動登入平台才發覺已審核通過……

註冊 TDX 平台會員

登入 TDX 平台後，前往會員中心 > (左邊) > 資料服務 > API金鑰頁面，對預設的API Key (或建立新的金鑰) 點擊 "編輯"，即可查看 "Client Id" 和 "Client Secret"，這兩組字串先記錄下來，之後 call API 時需要帶上。

API金鑰頁面

API 呼叫次數限制：

使用 API 金鑰呼叫，每個呼叫來源端 IP 呼叫次數限制為 50 次/秒 (無每日上限)。
不使用 API 金鑰呼叫，則僅能透過瀏覽器呼叫 API，且每個呼叫來源端 IP 的上限為每日 50 次。

有關 API 金鑰服務使用流程說明，請參考官方說明。

Swagger 工具

從上方導航欄開發指引 > API說明，前往 TDX 平台的 Swagger 工具，能查看有提供哪些 API，與各自的請求參數與回傳欄位說明。
詳細使用說明可以查看之前我寫的 PTX 介紹 (含 Odata 說明) 文章。

TDX 平台 Swagger 工具

右方有 Authorize 按鈕，填入 "Client Id" 與 "Client Secret" 驗證，即可使用你的 API 金鑰來呼叫。不使用 API 金鑰呼叫，有每日 50 次的上限。

API 認證授權機制

API 認證授權機制與 PTX 平台有蠻大的差異，簡單來說每次請求前要先身份認證取得 Access Token，才能使用 Access Token 來取得 TDX API 服務的數據資料。
(或使用尚未過期的 Access Token，有效期限預設為 1 天)

詳細步驟說明如下:

取得 Access Token

依照以下格式發出請求：

Request URL: https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token
Request Method: POST
Request Headers:
content-type: application/x-www-form-urlencoded
data:
grant_type: client_credentials
client_id: <your_client_id>
client_secret: <your_client_secret>

data 參數說明如下:

Key	Value
`grant_type`	固定使用 `client_credentials`
`client_id`	您的 Client Id，從 TDX 會員中心取得
`client_secret`	您的 Client Secret，從 TDX 會員中心取得

回傳資料是 JSON 格式，其中包含 access_token 參數，就是我們要的 Access Token。

呼叫 TDX API 服務，取得數據資料

Request URL: TDX_API_URI
Request Method: GET
Request Headers:
authorization: Bearer <Access_Token>

* 若 Access Token 時間超過有效期限(第一步驟收到回應中的 expires_in 參數)，則再重新透過第一步驟取得即可。

* 官方的說明文件： https://github.com/tdxmotc/SampleCode

完整 Python 程式範例

因為 TDX 平台的 API 一樣使用 OData (Open Data Protocol) 標準介面，所以這邊我就不再寫一次了，還不太懂的可前往「PTX 平台」API 介紹 (含 Odata 說明) 了解。

同樣以下方條件當範例查詢：

台鐵"台北"車站即時的列車到離站看板資訊，並且只要"逆行"的列車

查詢的 URL 會長得像這樣：
https://tdx.transportdata.tw/api/basic/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON

會發現與 PTX 平台根本一樣，只差在網址前方的部分。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import requests
client_id = '<your_client_id>'
client_secret = '<your_client_secret>'
class TDX():
def __init__(self, client_id, client_secret):
self.client_id = client_id
self.client_secret = client_secret
def get_token(self):
token_url = 'https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token'
headers = {'content-type': 'application/x-www-form-urlencoded'}
data = {
'grant_type': 'client_credentials',
'client_id': self.client_id,
'client_secret': self.client_secret
}
response = requests.post(token_url, headers=headers, data=data)
# print(response.status_code)
# print(response.json())
return response.json()['access_token']
def get_response(self, url):
headers = {'authorization': f'Bearer {self.get_token()}'}
response = requests.get(url, headers=headers)
return response.json()
if __name__ == '__main__':
tdx = TDX(client_id, client_secret)
# url = 'https://tdx.transportdata.tw/api/basic/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON'
base_url = "https://tdx.transportdata.tw/api"
# 取得指定[車站]列車即時到離站電子看板(動態前後30分鐘的車次)
endpoint = "/basic/v2/Rail/TRA/LiveBoard/Station/1000"
filter = "Direction eq 1" # 順逆行: [0:'順行', 1:'逆行']
url = f"{base_url}{endpoint}?$filter={filter}&$format=JSON"
response = tdx.get_response(url)
print(response)

如此應該就能順利取得資料 🎉🎉🎉

其他程式範例

除了參考我上面的 Python 範例，TDX 官方有提供 JavaScript 與 C# 程式語言的範例程式碼，需要的可前往參考 ( GitHub )。

我有寫一篇 Google Apps Script 範例程式可以參考。

也感謝熱心網友 meebox，提供 "適用在嵌入式系統的 MicroPython 環境、token 有效期判斷" 的版本：
https://github.com/codemee/tdx

結語

這次快速(?)帶大家了解「TDX 運輸資料流通服務平台」，看起來就是 PTX 平台的升級版，加入更多不同服務的資料。
如果你之前已經用 PTX 做些作品出來，不妨試著將其改串接至 TDX，畢竟可能明年 PTX 平台就無法使用了。

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
TDX 運輸資料流通服務平台 | 官網
 TDX API 說明 | Swagger 文件工具
 TDX 官方介接說明與範例程式碼 | GitHub
TDX 平台常見問題 | 官網

你不可能有先見之明，只能有後見之明，
因此，你必須相信，這些小事一定會和你的未來產生關聯。

—— 史蒂夫·賈伯斯

「PTX 公共運輸資訊平台」Google Apps Script 範例程式

jia@jiatool.com (Jia) — Sat, 14 May 2022 20:45:00 +0800

因部內目前已收攏資料於TDX運輸資訊整合流通服務平台，本平台預計將於2022/12/1落日，屆時您的會員金鑰將於2022/12/1起停用。
為避免您短時間內需移轉之困擾，即日起本平台不再受理審核會員註冊。
建議您依據身分類型至TDX申請會員，非常感謝您的支持。

前言

在之前的兩篇文章裡，我們分別介紹 PTX 公共運輸整合資訊流通服務平台整合多項大眾運輸的資料、說明 OData（Open Data Protocol）格式如何使用，與實際使用 Python 來串接 PTX 平台。

本篇文章將帶你換成使用 Google Apps Script 來串接 PTX 平台，取得這些相關數據資料 💾，還可以做出自己的簡易 API。
(Google Apps Script 其實是基於 JavaScript 來的，所以基本的語法大致都相同。)

關於 PTX 平台我寫了三篇文章來介紹與程式教學：

「PTX 公共運輸資訊平台」API 介紹 (含 Odata 說明)
「PTX 公共運輸資訊平台」Python 範例
「PTX 公共運輸資訊平台」Google Apps Script 範例 <– 本篇

PTX 公共運輸整合資訊流通服務平台

後來發現 PTX 竟然只服務到今年(2022年)底，之後會改以 TDX 運輸資訊整合流通服務平台，因此又特別寫一篇文章帶大家快速了解一下 TDX 平台：
「TDX 運輸資料流通服務平臺」含 Python 範例程式，PTX 平台的升級版~

創建 Google Apps Script 專案

可能有些人沒接觸過 Google Apps Script，我這邊先說明兩種創建的方式：

第一種到 Apps Script 頁面創建專案，預設會儲存在你 Google 雲端硬碟的根目錄。

創建 Google Apps Script 專案 -1

第二種在 Google 雲端硬碟裡新增 Google Apps Script 檔案 (如果選單內沒看到，可以點擊 "連結更多應用程式" 去尋找&加入)。

創建 Google Apps Script 專案 -2

選擇一種你順手的方式創建專案即可，好了我們就開始吧 🚌

API 認證授權機制

一樣先撰寫放在 Header 裡的 HMAC 認證授權 🔓，關於目前 PTX 平台採用 HMAC 認證授權機制說明，可以參考上一篇文章。

參數如下：

Key	Value
`Authorization`	`hmac username="APP ID", algorithm="hmac-sha1", headers="x-date", signature="Base64(HMAC-SHA1("x-date: " + x-date , APP Key))"`
`x-date`	`Wed, 19 Apr 2017 08:37:50 GMT`

※ 建議於每次請求 API 服務當下建立新的 signature，簽章時效性為 5 分鐘。

如果 HMAC 認證有問題、未符合身份驗證，它會回覆下列訊息：

HTTP Status Code 403：
- (1) HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication （x-date 的間隔時間超過定義的 clock skew 秒數）
- (2) HMAC signature does not match （日期格式正確，但簽章演算法有問題）
HTTP Status Code 401：
- (1) Unauthorized （未帶簽章，未經授權）

依照上方說明，使用 Google Apps Script 語法把這個 HMAC 編碼撰寫出來：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


function GetAuthorizationHeader() {
var AppID = '<YOUR APP ID>';
var AppKey = '<YOUR APP KEY>';
var xdate = new Date().toGMTString();
//HMAC-SHA1 運算
 var signature = Utilities.computeHmacSignature(Utilities.MacAlgorithm.HMAC_SHA_1, "x-date: " + xdate, AppKey);
//轉成Base64
 var HMAC = Utilities.base64Encode(signature);
var Authorization = 'hmac username=\"' + AppID + '\", algorithm=\"hmac-sha1\", headers=\"x-date\", signature=\"' + HMAC + '\"';
return { 'Authorization': Authorization, 'x-date': xdate ,'Accept-Encoding': 'gzip'};
}

Google Apps Script 程式範例

我們一樣使用上次的例子：

台鐵"台北"車站即時的列車到離站看板資訊，並且只要"逆行"的列車

先進到 PTX 平台的 Swagger 文件，找到 " 取得指定[車站]列車即時到離站電子看板 "：

列車即時到離站電子看板

填入 "台北車站" 代碼 1000 ( 車站代碼表 )，並依照下方 Responses 欄位說明 "Direction" 代表順逆行(0:'順行', 1:'逆行')，在 $filter 填入 Direction eq 1，指定 JSON 格式，最後點擊藍色 "Execute" 按鈕，看看回傳結果是不是我們想要的~

(關於這些 Odata 的寫法，我在第一篇文章有說明，忘記的可以回去看看)

它顯示的 "Request URL" 長得像這樣：
https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?%24filter=Direction%20eq%201&%24format=JSON

這是以下這句經過 URL 編碼後的結果：
(程式中 requests 會自動幫我們編碼，因此輸入底下這句也可以)
https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON

接下來將這些代入程式中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


function doGet() {
var response = UrlFetchApp.fetch(
"https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON",
{method: 'GET', 'headers': GetAuthorizationHeader()}
);
// console.log(response.getResponseCode());
 outData = JSON.parse(response.getContentText());
console.log(outData);
return ContentService.createTextOutput(JSON.stringify(outData)).setMimeType(ContentService.MimeType.JSON);
}

點擊上方的 "執行"，程式執行後會自動開啟 "執行記錄"，程式碼中 console.log(); 的部分會在此顯示出來。

如此即可順利取得資料 🎉🎉🎉

"執行" GAS 程式

完整 Google Apps Script 程式範例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


function doGet() {
var response = UrlFetchApp.fetch(
"https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON",
{method: 'GET', 'headers': GetAuthorizationHeader()}
);
// console.log(response.getResponseCode());
 outData = JSON.parse(response.getContentText());
console.log(outData);
return ContentService.createTextOutput(JSON.stringify(outData)).setMimeType(ContentService.MimeType.JSON);
}
function GetAuthorizationHeader() {
var AppID = '<YOUR APP ID>';
var AppKey = '<YOUR APP KEY>';
var xdate = new Date().toGMTString();
//HMAC-SHA1 運算
 var signature = Utilities.computeHmacSignature(Utilities.MacAlgorithm.HMAC_SHA_1, "x-date: " + xdate, AppKey);
//轉成Base64
 var HMAC = Utilities.base64Encode(signature);
var Authorization = 'hmac username=\"' + AppID + '\", algorithm=\"hmac-sha1\", headers=\"x-date\", signature=\"' + HMAC + '\"';
return { 'Authorization': Authorization, 'x-date': xdate ,'Accept-Encoding': 'gzip'};
}

部署

Google Apps Script 特別的地方就在於可直接把程式部署起來，不需要另外找伺服器、線上服務來處理，非常方便。

像是上面範例的 function doGet()，就是 Google Apps Script 內定的函式，當我們發佈成 "網頁應用程式" 後，對網址發送 GET 請求(就是在瀏覽器上前往此網址)，就會執行此函式。
另外也有 function doPost() 對應 POST 請求。

如果想在網址後方帶入參數，像是這樣：
https://webdomain.com?stationId=1000

就使用這種寫法，即可取到對應參數後方的字串：
var stationId = e.parameter.stationId;

帶入參數

那我們開始來 "部署" 吧~

確認檔案存檔後(重要！！)，點擊右上角的 "部署" > "新增部署作業" 按鈕。

選擇 "部署" > "新增部署作業"

左邊齒輪形狀的設定打開，選擇 "網頁應用程式"。

選擇 "網頁應用程式"

"執行身分" 和 "誰可以存取" 可以自己看需求更改，執行 "部署"。

執行部署

用這邊產生的網址，到瀏覽器貼上，就可以取得剛剛的資料了~

網頁應用程式網址

* 如果有編輯，需要存檔後再 "部署" 一次，而且網址會更改。但舊版本還會存在，需要到 "管理部署作業" 將其封存。

部署成網頁

除了像上述的方法當成一支 API，也可以回傳 HTML，顯示成網頁喔~

左邊檔案新增一個 HTML。

新增 HTML 檔案

HTML 檔案內容撰寫完成後，在原先的程式碼 doGet() 中，回傳這個 HTML 檔案即可。
(index 是 HTML 的檔名)

回傳 HTML

1
2
3


function doGet() {
return HtmlService.createHtmlOutputFromFile('index');
}

因此你可以在 Google Apps Script 裡，取得 PTX 平台大眾運輸資料後，顯示到自製的網頁上，嘗試做一個🚅查詢時刻表的網頁服務吧~

其他程式範例

除了參考我上面的 Google Apps Script 範例，PTX 官方也提供不同程式語言的範例程式碼提供開發者下載 ( GitHub )。

平台提供
- ASP.NET
- Java
- JavaScript
網友提供
- Bourne Shell
- C# 與 .NET Standard 2.0
- Go
- Go Client SDK - Code generated by go-swagger
- Node.js
- python
- Ruby
- Swift
- PHP
- Postman

結語

有關更多 Google Apps Script 語法說明，歡迎參考 Google Apps Script 官方文件。

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
公共運輸整合資訊流通服務平台 | 官網
 PTX 資料服務使用注意事項 | GitHub
PTX 官方範例程式碼 | GitHub
Google Apps Script 官方文件

我不是神童，只是堅持打好每一顆球。

—— 林昀儒 (台灣桌球國手)

「PTX 公共運輸資訊平台」Python 範例程式

jia@jiatool.com (Jia) — Sat, 30 Apr 2022 20:55:00 +0800

前言

在上一篇文章中，我們介紹了 PTX 公共運輸整合資訊流通服務平台，它整合公車、臺鐵、高鐵、捷運等多項公共運輸的資料服務 API，以及說明 OData（Open Data Protocol）標準介面格式如何使用。

本篇文章將帶你實際使用 Python 來串接 PTX 平台，取得這些相關數據資料 💾。

關於 PTX 平台我寫了三篇文章來介紹與程式教學：

PTX 公共運輸整合資訊流通服務平台

API 認證授權機制

目前 PTX 平台採用 HMAC 認證授權機制，在送出請求時 headers 需代上規定的資料，它會依照 HTTP header 資訊來判別用戶是否有授權身份 🔓。

官方說明如下：

HMAC 機制：以 HMAC 簽章驗證使用者的身份，用戶在請求 API 服務時，將 APP Key 與當下時間(格式請使用GMT時間) 做 HMAC-SHA1 運算後轉成 Base64 格式，帶入 signature 屬性欄位，服務器端將驗證用戶請求時的 header 欄位，驗證使用者的身份及請求服務的時效性。

HMAC Signature 簽章時效性：於 MOTC Helper 該網頁測試時，請在最上方輸入 API Key 與 API ID (請再次確認是否有把 APP Key 跟 ID 填寫正確，若欄位資訊相反會無法執行)。點選 Explore ，每次請求下方 API 時，會於 header 帶入 Authorization 及 x-date ，依照請求當下的時間 & API Key 製作簽章。

參數如下：

Key	Value
`Authorization`	`hmac username="APP ID", algorithm="hmac-sha1", headers="x-date", signature="Base64(HMAC-SHA1("x-date: " + x-date , APP Key))"`
`x-date`	`Wed, 19 Apr 2017 08:37:50 GMT`

※ 建議於每次請求 API 服務當下建立新的 signature，簽章時效性為 5 分鐘。

如果 HMAC 認證有問題、未符合身份驗證，它會回覆下列訊息：

HTTP Status Code 403：
- (1) HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication （x-date 的間隔時間超過定義的 clock skew 秒數）
- (2) HMAC signature does not match （日期格式正確，但簽章演算法有問題）
HTTP Status Code 401：
- (1) Unauthorized （未帶簽章，未經授權）

依照上方說明，使用 Python 把這個 HMAC 編碼寫出來，這邊我也是參考範例來做修改的。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


class Auth():
def __init__(self, app_id, app_key):
self.app_id = app_id
self.app_key = app_key
def get_auth_header(self):
xdate = datetime.utcnow().strftime("%a, %d %b %Y %H:%M:%S GMT")
hashed = hmac.new(self.app_key.encode('utf8'), (f'x-date: {xdate}').encode('utf8'), sha1)
signature = base64.b64encode(hashed.digest()).decode()
authorization = (f'hmac username="{self.app_id}", algorithm="hmac-sha1"' +
f', headers="x-date", signature="{signature}"')
return {
'Authorization': authorization,
'x-date': xdate,
'Accept-Encoding': 'gzip'
}

Python 程式範例

我們來實際舉個例子，像是我想抓：

台鐵"台北"車站即時的列車到離站看板資訊，並且只要"逆行"的列車

先進到 PTX 平台的 Swagger 文件，找到 " 取得指定[車站]列車即時到離站電子看板 "：

列車即時到離站電子看板

(關於這些 Odata 的寫法，我在上一篇文章有說明，忘記的可以回去看看)

它顯示的 "Request URL" 長得像這樣：
https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?%24filter=Direction%20eq%201&%24format=JSON

接下來將這些代入程式中：

1
2
3
4


auth = Auth(app_id, app_key)
url = "https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON"
response = requests.get(url, headers=auth.get_auth_header())
print(response.json())

如此應該就能順利取得資料 🎉🎉🎉

完整 Python 程式範例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


import hmac
import base64
import requests
from datetime import datetime
from hashlib import sha1
app_id = '<YOUR APP ID>'
app_key = '<YOUR APP KEY>'
class Auth():
def __init__(self, app_id, app_key):
self.app_id = app_id
self.app_key = app_key
def get_auth_header(self):
xdate = datetime.utcnow().strftime("%a, %d %b %Y %H:%M:%S GMT")
hashed = hmac.new(self.app_key.encode('utf8'), (f'x-date: {xdate}').encode('utf8'), sha1)
signature = base64.b64encode(hashed.digest()).decode()
authorization = (f'hmac username="{self.app_id}", algorithm="hmac-sha1"' +
f', headers="x-date", signature="{signature}"')
return {
'Authorization': authorization,
'x-date': xdate,
'Accept-Encoding': 'gzip'
}
if __name__ == '__main__':
auth = Auth(app_id, app_key)
base_url = "https://ptx.transportdata.tw"
# 取得指定[車站]列車即時到離站電子看板(動態前後30分鐘的車次)
endpoint = "/MOTC/v2/Rail/TRA/LiveBoard/Station/1000"
filter = "Direction eq 1" # 順逆行: [0:'順行', 1:'逆行']
url = f"{base_url}{endpoint}?$filter={filter}&$format=JSON"
response = requests.get(url, headers=auth.get_auth_header())
print(response.json())

其他程式範例

除了參考我上面的 Python 範例，PTX 官方也提供不同程式語言的範例程式碼提供開發者下載 ( GitHub )。

平台提供
- ASP.NET
- Java
- JavaScript
網友提供
- Bourne Shell
- C# 與 .NET Standard 2.0
- Go
- Go Client SDK - Code generated by go-swagger
- Node.js
- python
- Ruby
- Swift
- PHP
- Postman

另外，在下一篇文章裡，我會分享 Google Apps Script 的範例程式，它跟一般 JavaScript 有一些些不同，Google Apps Script 中預設應該是不能使用 jQuery，還有編碼的寫法也有些不同。

結語

除了以上文章的解說，也可以看看官方的文件說明。
有針對 "航空"、"公車"、"雙鐵(台鐵/高鐵)" 資料做進一步的說明，如果有使用到此 API 服務的人，建議進入先了解。
* 不過我看此文件上次更新時間 2018/04/12，可能有些資料不是最新的。

上一篇了解 PTX 平台的說明與 OData 介面，本篇則教你如何透過 Python 程式來發出請求、獲取資料，快將你有趣的 idea 來動手做實現它吧~

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
公共運輸整合資訊流通服務平台 | 官網
 PTX 資料服務使用注意事項 | GitHub
PTX 官方範例程式碼 | GitHub

專注你喜歡的事，就能感受到那股強大的力量。

—— 戴資穎 (台灣羽球國手)

「PTX 公共運輸資訊平台」API 介紹 (含 Odata 說明)

jia@jiatool.com (Jia) — Sat, 23 Apr 2022 20:45:00 +0800

前言

你手機裡很可能有安裝臺鐵、高鐵、捷運、公車等等公共運輸的 APP，或者使用過查詢時刻表、動態相關網站( 示範應用列表 )，但他們是怎麼取得這些資料的呢？

原來有個政府的平台 — 公共運輸整合資訊流通服務平台，它整合並提供這些數據資料，以 Web API 的形式提供我們串接。

關於 PTX 平台我寫了三篇文章來介紹與程式教學：

「PTX 公共運輸資訊平台」API 介紹 (含 Odata 說明) <– 本篇
「PTX 公共運輸資訊平台」Python 範例
「PTX 公共運輸資訊平台」Google Apps Script 範例

PTX 公共運輸整合資訊流通服務平台

PTX 簡介

為了推動公共運輸整合資訊開放 (Open Data) 、統整各機關(構)的多元公共運輸資訊，交通部推出了這個 PTX 平台，包含了臺灣的公車、臺鐵、高鐵、捷運、航空、自行車、航運(海運)、觀光景點等公共運輸資料服務 API，非常的多樣，幾乎在臺灣你想的到的大眾交通工具都包在裡頭。
像是：臺鐵票價資料、高雄輕軌時刻表、臺北捷運即時通阻事件、機場即時入境航班、公車即時位置、公共自行車剩餘數量、觀光景點……等等。

PTX 網站有個「各項服務查詢」供檢視平台提供的服務，能依照 "領域類型"、"資料類型"、"業管機關" 去做篩選，每個服務還可以快速點開 API 說明及網址範例，另外還有整理成表格顯示：目前各單位資料供應現況表。

PTX 各項服務查詢

加入會員 & 取得 APP ID 與 APP Key

為了提供穩定的服務、加強資訊安全管理，要使用此平台的 API 前需要先加入會員。

加入會員

進入加入會員頁面，在此選擇「一般會員」即可，「進階會員」、「專案用戶」有更多的呼叫次數及其他權益，但那還要提供額外的證明，一般會員的 API 呼叫次數上限 20,000 次/日已經很夠我們自己玩玩，或做個小應用了。
(因為我以前註冊過，這邊就不演示了，按照網頁流程操作應該不會有什麼問題。)

申請加入 PTX 會員

取得 APP ID 與 APP Key

(APP ID 與 APP Key 下一篇文章使用 Python 實際操作時才會用到)

註冊完成並等待三個工作日審核後，會收到一封 Email，之後我們會使用到「基礎資料服務(L1)」的「APP ID」與「APP Key」。
而目前提供的資料服務多屬 L1，L2 的服務目前僅有場站空氣品質服務 (不知道現在 L2 是否有加入其他的服務)。

或者也可登入後到 API金鑰申請取得，如果忘記 APP Key 可點擊「忘記APP Key」即可，但要注意舊的 APP Key 就會失效，所以如果你 APP Key 不小心公開了也可由此來重新產生，避免額度被其他人使用。

取得 APP ID 與 APP Key

API 說明

可以參考官方提供的「資料使用葵花寶典」，此手冊分成以下四點作介紹說明

API 會員：各會員層級進行說明並提供會員申請流程。
API 使用說明：API 呼叫方法及注意事項進行說明。
API 特色說明：API 獨特的使用技巧進行說明。
API 資料使用注意事項：各運具資料面注意事項進行說明。

PTX 的 API 是以 OData（Open Data Protocol）標準介面格式對外開放供使用。

URI 設計概念

先來看看 URI 的設計概念。

這邊以臺鐵 "取得指定[日期],[車站]的站別時刻表資料" 為例：

臺鐵 "取得指定[日期],[車站]的站別時刻表資料"

從這張圖可以清楚的看出來，最前方 "基本網址" 大家都一樣，再來是 "API版本"、"鐵道" 中的 "臺鐵"，我們想抓的 "站別時刻表"，以及最後方帶入的參數 "車站代碼" 與 "日期"。
(車站代碼可以從另外一個 "車站基本資料" API 取得，或臺鐵官網的車站代碼表 )

雖然每項服務會有些不同，但其網址結構都是差不多的，這邊稍微知道就好，詳細說明請參考官方提供的「 API URI Convention文件」。

Swagger 文件工具

至於各項服務 API 說明可以從這裡進入，或到「 PTX 各項服務查詢」點擊對應服務右方的"服務說明"，它是透過 Swagger 這個文件工具來呈現。

這邊先講個 Swagger 基本使用。

找一個感興趣的資源(Resource)，並打開其 API 說明。

API 說明

大致分為幾個部分，最上方針對此資源簡短描述，再來 "Parameters" 是此資源可附加上的參數，像是我想看哪一個捷運系統的車站資料，就是在這邊帶上參數，除了標示 required 紅字為必填，其餘我們先暫時不必理會。最後 "Responses" 會寫到當回應哪個 HTTP Status Code 對應是哪個意思，其回應資料格式又是長什麼樣子。

API 說明

回應資料有些欄位可能看不出它代表意思，就可以到這邊找找說明。

API 說明

在 Parameters 與 Responses 中間有個大大的藍色 "Execute" 按鈕，我們給他用力按下去。

噹🌟！發現在底下 "Responses" 區塊跑出好幾個新東西：

"Request URL" 代表依照你上方設定的參數，其請求網址會長怎樣。
"Server response" 顯示回應 HTTP Status Code 及回應內容(Response body)，回應內容就是我們想要的資料啦~

API 回應說明

這個 Swagger 工具大致上的用法就是這樣。

到這邊，都可以如實拿到想要的資料了。

但可能它每次回傳的資料量很大，我只是需要其中的一部分資料而已，這樣會浪費頻寬、增加回應時間、接收到資料後還要費力處理，那有沒有能在送出請求時，就告訴 Server 我們想要那些資料呢？
有的！！接下來就要講到 Odata 這個介面格式厲害的地方了😮

Odata 查詢語法

通過 Odata 協定制定的用法，我們可以去做多樣的查詢、過濾、排序，甚至有更進階的函數語法。

我會依序介紹以下六種 Odata 的查詢方法：

$format 指定來源格式
$orderby 排序
$top 取前幾筆
$skip 跳過前幾筆
$select 挑選
$filter 過濾

這邊我是依照比較好理解的順序介紹說明，最後再舉幾個複合範例給各位參考。

$format 指定來源格式

指定回傳資料要以什麼格式。

PTX 提供 JSON 與 XML 兩種格式供選擇。

$format=json
$format=xml

$orderby 排序

指定回傳資料的排序。

升冪：由小到大；降冪：由大到小。

針對欄位1作升冪 (預設)
$orderby=Field1
$orderby=Field1 asc
針對欄位1作降冪
$orderby=Field1 desc
針對欄位1作升冪，欄位2降冪
$orderby=Field1 asc,Field2 desc

各 API 服務有不同的回傳資料，例如我在查詢公共自行車即時車位時，希望資料依照 "可租借數量" 由多至少排列：
$orderby=AvailableRentBikes desc

$top $skip 取前幾筆

這兩個是類似的概念。

$top：取前幾筆資料。
$skip 跳過前幾筆資料。

像是我想拿取前 11~30 筆資料：
$top=20&$skip=10

$select 挑選

指定只需要回傳那些欄位，多個欄位可用逗號(,)隔開，未指定則回傳全部欄位。
(目前只支援第一層欄位)

只回傳欄位1
$select=Field1
回傳多個欄位，欄位1和欄位2
$select=Field1,Field2

不過它有但書：

回傳資料指定為 json 時，只會回傳被 select 的欄位，除此之外，若其他欄位為非 nullable，也會回傳系統預設值。
回傳資料指定為 xml，沒有被指定的屬性若為 class 或是 string，不會回傳該欄位，但若是其他屬性(int,bool,enum..)，還是會回傳該欄位，其值為系統預設值。

$filter 過濾

(來到最複雜、最多變化的一個語法了😅)

filter 語法是用來對資料做篩選、過濾，提供「邏輯運算子」、「算術運算子」、「規範函數」、「Lambda Operators」可使用。

邏輯運算子 (Logical Operators)

邏輯運算子	意義
eq	等於
ne	不等於
gt	大於
ge	大於等於
lt	小於
le	小於等於
and	而且、和
or	或者
not	否定

例如想查詢公共自行車 "可租借數量" 大於 10 台的站點：
$filter=AvailableRentBikes gt 10
假如欄位是在第二層，則可透過 / 連接。
例如想取得高雄捷運 "左營站 " 的即時到離站電子看板：
$filter=StationName/Zh_tw eq '左營'

* 要注意後方比對的字串需使用單引號 ' 框起來，雙引號 " 是不行的哦。

算術運算子 (Arithmetic Operators)

算數運算子	意義
add	加
sub	減
mul	乘
div	除
mod	餘數

例如我想查詢有哪台公車目前時速是奇數：
$filter=Speed mod 2 eq 1
(知道這個好像也不能幹嘛……)

規範函數 (Canonical Functions)

規範函數	意義	規範函數	意義
substring	子字串	year	年份
startswith	字串開頭	month	月份
endswith	字串結尾	day	日
length	字串長度	hour	小時
indexof	指定字串出現位置	minute	分
tolower	字串變小寫	second	秒
toupper	字串變大寫	fractionalseconds	小數秒
trim	去空白	date	日期
contains	包含	time	時間
concat	串接
		round	四捨五入
		floor	無條件捨去
		ceiling	無條件進位
		cast	轉型

例如取得公車動態中車牌號碼開頭是 "001" 的資料：
$filter=startswith(PlateNumb, '001')
或者想知道車牌號碼長度為 7 個字的公車：
$filter=length(PlateNumb) eq 7
去台南旅遊，想找出店名包含 "豆花" 的店家：
$filter=contains(RestaurantName,'豆花')

Lambda Operators

Lambda Operators	意義
all	所有項目都要符合
any	其中一項符合

例如我想知道今天有哪幾班高鐵會停 "雲林"：
$filter=StopTimes/any(d:d/StationName/Zh_tw eq '雲林')

這部分可能一開始有些難懂，主要是用在判斷陣列中的值。
* 其中的 d 是可以隨意換其他名稱的。

多種複合用法

為了讓大家更容易理解，這邊我再舉幾個多種語法所組合的用法：

想看看高鐵在今年(2022年) 3 月之後有發布什麼關於 "左營" 的最新消息：
$filter=year(PublishTime) eq 2022 and month(PublishTime) ge 3 and contains(Title,'左營')
(啊…4/1 水泥施工事故導致電力異常，台南-左營站間停駛)
台南市公車中，路線是 "紅" 字開頭，並且目前 "時速超過 30 公里"，依照時速由大排到小的前五名：
$filter=startswith(SubRouteName/Zh_tw,'紅') and Speed gt 30&$orderby=Speed desc&$top=5
因為提著大包小包，想知道台北捷運 "古亭站" 有哪個出口有 "電扶梯" 或 "電梯"，且只回傳 "出口" 和 "地址"：
(備註：Escalator 是否有電扶梯(0:沒有,1:雙向,2:出站,3:入站))
$select=ExitName,LocationDescription&$filter=StationName/Zh_tw eq '古亭' and (Escalator ne 0 or Elevator eq true)

有關如何使用 Odata 查詢 PTX API 資料，官方有整裡個簡報—「 PTX APIs開發技術說明(含Odata) 」，裡頭有更詳細地介紹 Odata，以及其查詢選項、函數語法。

當然，如果你覺得這些篩選語法太麻煩，也是可以全部抓下來後，再使用程式去處理。

API 呼叫統計

PTX 平台也提供「服務呼叫統計」網頁，可查看自己目前的資料數據傳輸量、呼叫次數以及虛擬點數等等統計數據，確認還有多少額度可以使用，甚至也針對各項服務做統計。

PTX 服務呼叫統計

結語

有了這個 PTX 平台後，想要取得各大眾公共運輸的資料變得相當容易，除了做成應用程式自用外，也可以公開讓大家使用。

官方也有整理一些常見問題供參考。

如何？看完介紹後你腦中是否產生有趣的 idea 了呢😙
別急，下一篇文章會來教你該如何使用 Python 來串接 PTX API ，以及需要注意什麼事情。

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
公共運輸整合資訊流通服務平台 | 官網
 PTX 資料使用葵花寶典
 PTX API 說明 | Swagger
PTX APIs開發技術說明(含Odata)

等待奇蹟，不如為自己留下努力的軌跡；期待運氣，不如堅持自己的勇氣。

—— 李洋 (台灣羽球國手)

(圖解) 網路爬蟲 API 常見的 3 種「翻頁」方式

jia@jiatool.com (Jia) — Sat, 10 Jul 2021 20:40:00 +0800

前言

之前時不時有網友在詢問有關網路爬蟲"翻頁"的問題：

我該如何抓取下一頁的文章呢？
使用 limit 最多只能抓到前 100 筆留言，那之後的該怎麼取得？

我發覺可能之前 Python 網路爬蟲實例系列內沒有說明清楚。
因此這篇文章，將整理目前我遇過的網路爬蟲 API 中，常遇見的三種「翻頁」方式，並且搭配簡易圖示，希望讓剛進此領域的網友能更容易理解。

圖片來源：Pexels

說明

想要爬取某個網站，也順利找出網頁是使用動態載入請求 API 的方式，但遇到像 Dcard 這種的文章列表或留言列表，它是往下滾，就會送出新請求來取得下一頁資料。

那麼，它是如何達成「翻頁」的呢？

底下會依照這三種常遇到的「翻頁」方式來分別說明：

頁數 (page)
偏移 (limit & offset)
指定ID (pid)

頁數 (page)

翻頁方式 - 頁數

第一種最容易理解、最直覺的是頁數，這就跟我們一般瀏覽網頁一樣，你想要看第幾頁，就給它第幾頁的頁數即可。

page 代表資料的頁數。

不過缺點是不能彈性調整每次抓取的量，假如此 API 一頁是 30 則留言，就算我只想取前 5 則留言，一樣一次請求還是會抓到 30 則留言，除了會占用較多流量，也可能花費較多時間。

舉例來說：
想抓第一頁 page=1，想抓第二頁是 page=2，同理第99頁就是 page=99。

實際網站範例：
「 PChome 線上購物」"商品搜尋"中的 page。
「聯合新聞網」"文章列表"中的 page。

偏移 (limit & offset)

翻頁方式 - 偏移

第二種翻頁方式就解決了第一種的問題，變成可「彈性調整抓取量」。
它藉由兩個參數來達成，分別為"limit"與"offset" (不同 API 參數名稱可能不同)

limit 代表一次請求最大資料筆數。
offset 代表資料的偏移值。

* offset(foodpanda)參數在不同網站的 API 有不同名稱，例如 newest(蝦皮購物)、after(Dcard)。

舉例來說：
抓前三筆資料是 limit=3 offset=0。
想取得第六、七筆資料，將資料偏移 5 (從第一筆資料開始往下加五筆的意思)、限制一次 2 筆，就是 limit=2 offset=5。

實際網站範例：
「 foodpanda 」"搜尋餐廳"中的 limit 和 offset。
「蝦皮購物」"搜尋商品"中的 limit 和 newest。
「 Dcard API 」"留言列表"中的 limit 和 after。

指定ID (pid)

翻頁方式 - 指定ID

第三種翻頁方式感覺像是第二種的改版，有些網站一樣有"limit"來限制最大資料筆數，但"offset"換成了"pid"參數，"pid"參數需要帶入上一頁最後一筆資料的數值。
但它就限制了你，不能直接跳到後面的頁數，例如我想看第 100 筆資料，你還是要請求一頁才知道下一頁的網址。

limit 代表一次請求最大資料筆數。
pid 上一頁最後一筆的 ID。

* pid(NOWnews)參數在不同網站的 API 有不同名稱，例如 before(Dcard)、pageToken(YouTube Data API)。而 NOWnews 不需要 limit 參數，它 API 已經有限制一次的資料量了。

舉例來說：
抓前三筆資料是 limit=3 pid=，因為這是最前面的資料，pid 就不需要給值。
而取得第四、五筆資料，因為只要兩筆，limit 帶入 2，前一頁最後一筆資料 ID 為 003，因此 pid 帶入 003，結果就是 limit=2 pid=003。

實際網站範例：
「 NOWnews今日新聞」"新聞列表"中的 pid。
「 Dcard API 」"文章列表"中的 limit 和 before。
「 YouTube Data API 」"留言列表"中的 maxResults 和 pageToken。

注意：YouTube Data API 的 pageToken 有點不太一樣，它是帶入上一頁回傳的的 nextPageToken，而不是最後一筆資料的 ID。

三者方式比較

我進一步將以上三種翻頁方式放在一起比較，如下圖範例所示。

假如左邊是此 API 可以獲取的全部資料，可以看到共有五篇文章，各自有 ID(id) 和標題(title) 欄位，同樣要取得綠色區塊(第三和第四篇文章)，以上三種翻頁方式實際會需要帶入這些數值。

三種翻頁方式比較

頁數：假設它一頁是兩筆資料，那我們要帶入 pega=2 來取到第二頁資料。
偏移：一次想取兩筆資料，因此 limit=2；我們要從第三筆開始取，因此 offset=2。
指定ID：一次想取兩筆資料，因此 limit=2；上一頁最後一筆資料的 ID 是 002，因此 pid=002。

結語

不知道透過上面的說明與比較，是不是讓你對於 API 常見的幾種翻頁方式更了解了呢？
提醒各網站 API 本身可能有些微差異，詳細規則還是要查看 API 文件。

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

Stay hungry. Stay foolish
求知若飢，虛心若愚。

—— 史蒂夫·賈伯斯

Google 搜尋結果 API — Aves API 完整教學

jia@jiatool.com (Jia) — Sat, 30 Jan 2021 20:55:00 +0800

(先澄清，以下非業配，純粹依個人使用過程描述。)

前言

因為某原因，需要爬取"Google 搜尋"頁面上的資料，沒多久前舊有的網頁爬蟲請求失敗了!! (不妙啊…

後來多次嘗試，也改用手機網路分享(不同IP)測試，也是遇到同樣的問題"HTTP Error 429: Too Many Requests"，並需要通過 reCAPTCHA 驗證。
📢 白話翻譯：你短時間送出太多請求了，一般人不可能這麼頻繁，我嚴重懷疑你是機器人，先出個題目讓你回答( 順便賺個免費勞工幫我們訓練機器學習 )，等確定你是真人再給你資料。

後來想說為了穩定及時間因素，不要我們自己手動爬取、絞盡腦汁突破了，請求外援看看XD

Photo by Harry Brewer on Unsplash

尋找 Google 搜尋 API

先去 Google 官網看看是否提供對應功能的 API，結果是有 Custom Search JSON API ，但每天只免費提供 100 次搜尋，額外請求的費用為每 1000 個搜尋 5 美元，每天最多 1 萬次搜尋。
這對我來說免費額度遠遠不夠，加購的價格又超貴 QAQ

官方提供的不行，不然找找看網路上，有沒有別人提供免費或付費的 Google 搜尋 API 服務可以使用呢？因為感覺某些資訊公司也會有這種需求。

後來找到「 Aves API 」，其他有提供類似的服務還有「 SerpApi 」、「 Rapid API 」、「 zenserp 」、「 ScraperBox 」、「 DataForSEO 」……等可以參考，多方去比較，找到最符合自己需求的服務。

最後我選擇 Aves API，會選擇這個最主要的因素 – 便宜😅，這是我目前找到最便宜的，而且它計費的方式與其他有些不同，它是類似儲值的概念，你用多少就扣多少，沒有時間上的限制，而其他比較常見的是按月付款。

Aves API 官網

測試頁面

在 Aves API 官網首頁上有個可以實際輸入關鍵字，查看它回傳的資料是那些、長怎麼樣的即時測試頁面(Live Demo) ，能在此先測試是否有符合自己的需求。

即時測試頁面(Live Demo)

API 相關文檔

官方網站 API 文檔

錯誤狀態代碼

如果請求收到錯誤狀態代碼，可以在這邊查看是什麼原因，例如：API 金鑰無效、缺少查詢參數、帳戶額度不足。

API 參數

註冊後會取得唯一的 API Key(金鑰)，送出請求時要代入。
API 網址如下：

https://api.avesapi.com/search?apikey=YOUR_API_KEY

(使用 GET 方式送出請求，等同於你在瀏覽器直接輸入網址啦！)

而此 API 目前可帶參數有以下這些：

參數	代表意思	預設
`apikey`	[必要] 你的 API Key(金鑰)。	[無]
`query`	[必要] 要搜尋的關鍵字。	[無]
`device`	指定搜尋裝置平台：`desktop` 或 `mobile`。	`desktop`
`location`	指定位置參數，有助於取得基於位置的搜索結果。提供的位置在 places.json 此檔案內所列出來的，需要的話就帶入`place_slug`中的值。台灣可以使用`"tw"`在檔案內搜尋，例如有`taipei`、`taichung`、`tainan`、`kaohsiung`等地點。	[無]
`google_domain`	指定 Google 網域，支援的列表 google-domains.json 。台灣是 `google.com.tw`。	`google.com`
`gl`	指定查詢的國家代碼(預設美國)，支援的列表 countries.json 。台灣是 `tw`。	`us`
`hl`	指定查詢的語言(預設美語)，支援的列表 languages.json 。繁體中文是 `Chinese (Traditional)`。	`en`
`num`	指定每頁顯示的結果數，測試最多到`100`。	`10`
`page`	指定頁數(1~10頁)。	`1`
`uule`	Returns the location based search results. (好像可以設定精確位置，但我不了解。)	[無]
`output`	API 回應資料的格式：`json` 或 `html`。	`json`

* 還有我發現在它 API Playground 頁面，還有一個的參數是type，代表搜尋種類，有 web(預設)、image、news 可選，但這個參數我還沒實際試過。

使用範例

舉例來說，我想要在 google.com.tw 網域上搜尋"手機"，國家設定台灣、語言當然是繁體中文，想要看前 100 個搜尋結果，就如下代入參數請求：

https://api.avesapi.com/search?apikey={your-api-key}&query=手機&google_domain=google.com.tw&gl=tw&hl=zh-tw&num=100

或者參數也可以以字典(Dictionary)的方式呈現。
在此使用 Python 程式來示範。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


your_api_key = 'XXXXXXXXXX'
keyword = '手機'
api_url = 'https://api.avesapi.com/search'
params = {
'apikey': your_api_key,
'type': 'web',
'query': keyword,
'device': 'desktop',
'google_domain': 'google.com.tw',
'gl': 'tw',
'hl': 'zh-tw',
'output': 'json',
'num': 100
}
r = requests.get(url=api_url, params=params, timeout=35)
if r.status_code == requests.codes.ok:
print(r.json())

回應資料如此： avesapi_data.json

除了一般的搜尋結果與排名，如果搜尋結果內還有"圖片"、"影片"、"地圖"、"相關搜尋關鍵字"，它一樣也可以取得。

圖片範例

影片範例

地圖範例

相關搜尋關鍵字範例

網站後台

當你註冊後登入，即可進入後台頁面去查看更多相關資訊。

其中有幾個重要的頁面：

儀錶板(Dashboard)

像是你還剩多少額度、最近請求的紀錄、每天使用量等等，以圖表來呈現。

Dashboard 頁面

API Playground

API Playground 以圖形化的操作頁面，讓你可以實際選擇參數、送出請求，並查看回傳的資料。如果你發現使用自己寫的程式，都沒有成功的話，也可以在此頁面測試，藉此排除是否是 API 的問題。
但要注意，這邊請求會帶上自己的 API Key，因此每一次請求也是會扣積分的哦！

API Playground 頁面

剩下的是一些購買頁面、購買紀錄、個人資料等等，這邊我就不展示了。

注意事項

有時因他們伺服器問題，會發生請求回應失敗，無法取得資料的情況，這時再重新送出請求一次即可，這個不會扣除積分。
使用發現有時請求會發生 timeout 逾時，沒有成功取得資料，但卻還是被扣了一個積分額度。
與客服聯繫後得知，此 API 請求最大 timeout 為 30 秒，也就是說如果我requests.get(url, timeout=20) 設定 20 秒，但伺服器在 25 秒時才回覆資料，那我程式這邊雖然是 timeout，但他們是有送出資料(一樣算成功請求，會被扣積分)。所以建議 requests 中 timeout 要設定大於 30 秒。
API 文檔有列出一些禁止的關鍵字，例如：site:、domain:、title:、before:……，可能因為這些進階查詢讓他們系統比較容易被檔吧(?)，如果使用這類關鍵字查詢的話，每個成功請求會被扣 25 個積分。

結語

因為 Google 搜尋結果相關的 API 我也只使用過這一款，所以沒辦法跟你說是不是這個就是最好，但其實這類的服務大同小異，需要的話可以自行比較看看，官網文檔是否完整詳細、客服回應速度如何、是否提供台灣中文搜尋參數、計費方式、網路上別人的評價推薦。
最好也註冊一個帳號，用免費的額度嘗試，是否有達到自己的需求。

* 要注意某些網站可能沒有提供免費額度

參考：
Google Custom Search JSON API 官網
 Aves API 官網

又一天過去了。今天覺得如何呢？
夢想是不是又更遠了？

—— 每天來點負能量

[Python爬蟲實例] YouTube-使用 YouTube Data API

jia@jiatool.com (Jia) — Sun, 01 Nov 2020 20:40:00 +0800

前言

來到 Python網路爬蟲實例系列第四篇，本篇使用 Python 透過官方 YouTube Data API v3 來爬取 YouTube ，包含頻道資訊、影片清單、影片資訊等等資料。

從在 Google 雲端平台(Google Cloud Platform)創建一個專案開始，包括獲取 API 授權憑證、取得 API key，到撰寫抓取程式皆會一步步講解如何操作。最後同樣會附上完整程式碼供參考。

而如果你是想下載 YouTube 影片的話，本篇內容並不會提及，這部分可參考其他套件，例如 pytube 。
之前還有另外一個套件 Youtube-dl，但在寫這篇文章時發現美國唱片業協會（RIAA）點名 Youtube-dl 程式碼違反著作權法，並要求GitHub將它們移除( 來源 )。

備註：此文僅教育學習，切勿用作商業用途，個人實作皆屬個人行為，本作者不負任何法律責任

套件

本次主要使用到的套件：

Requests [ Doc ] [ GitHub ]

流程

要使用官方 YouTube Data API 抓取資料前，要先取得 API Key。

先到 Google 雲端平台(Google Cloud Platform)創建一個專案，並將 YouTube Data API 加入置專案內，獲取 API 授權憑證、取得 API key。

爬取資料這邊以 六指淵 Huber 頻道當範例，到上傳的影片列表抓取最新的前五則影片，再到影片內取得影片相關資訊及留言。

六指淵 Huber 頻道

🔑 取得 YouTube Data API Key

先到 Google 雲端平台(Google Cloud Platform) 創建一個專案，如果是第一次進來會跳出服務條款，點選同意後繼續。
點擊右上角顯示"建立專案"，或到上方的"選取專案"處建立。

服務條款

右上角"新增專案"。

創建專案

輸入"專案名稱"，點選"建立"。
(專案ID也可以修改)

創建專案

等它跑完後會進到此頁面，接下來要將我們需要使用的 API 加進來啟用。
點選"啟用 API 和服務"。

啟用 API

找到 YouTube Data API v3。

啟用 API

點擊"啟用"。

啟用 API

最後要建立憑證，並取得 API Key。
點擊右方"建立憑證"，或者點擊左方的"憑證"。

建立憑證

如果你是點擊左方"憑證"，則依下圖所示建立 API 金鑰 (API Key)。

建立憑證

如果你是點擊右方"建立憑證"，則依下圖選擇，並點擊"我需要那些憑證"。

建立憑證

它會跳到此頁面，將 API 金鑰複製下來，待之後程式使用。
(也可以"為金鑰新增限制")

建立憑證

到這邊就完成 YouTube Data API Key 的取得，看似步驟很多，但實際操作過一遍就會了解了。

* 官方說明文檔

📘 爬蟲程式

本次是直接使用 API，因此在送出請求時就不需要加入 header 中 User-Agent 欄位了。

先在上方定義剛剛取得的 API Key，待之後發出請求時帶入。
(YOUR_YOUTUBE_API_KEY 換成剛剛在上一步取得的 API Key)

1

YOUTUBE_API_KEY = "YOUR_YOUTUBE_API_KEY"

API 說明

在官方 API 文件內，可以查詢各種資源及各種請求方法。

在本次程式中會用到幾種資源 (這邊都只需使用 list 方法)：

channels ：取得頻道"上傳影片清單"的 ID
playlistItems ：取得清單中的影片列表
videos ：取得影片資訊
commentThreads ：取得影片底下留言

本教學都只使用到 list 方法(GET)，因此網址串好後可以直接貼到瀏覽器上測試，觀看它回傳的資料。

因為每一次送出請求皆需要帶上 API Key，而且回傳資料要轉換JSON，所以可以另外寫一個用於組合網址、請求的函式，也可在裡面做當請求失敗的處理。

1
2
3
4
5
6
7
8
9


def get_html_to_json(self, path):
"""組合 URL 後 GET 網頁並轉換成 JSON"""
api_url = f"{self.base_url}{path}&key={self.api_key}"
r = requests.get(api_url)
if r.status_code == requests.codes.ok:
data = r.json()
else:
data = None
return data

* 為了較清楚的了解流程，以下範例程式內沒有加入太多的例外處理。

取得頻道"上傳影片"清單的 ID

想要抓取頻道內上傳的影片前，需要先抓到"上傳影片"清單的 ID，再用此 ID 去取的影片清單。

使用 channels 路徑來取得，需帶上"id"、"key"、"part"等查詢參數。
id 代表頻道 ID；key 代表我們的 API Key；part 代表想取得的資源屬性。

頻道ID的取得方式可以先到頻道首頁，觀察網址後方帶的數值，例如：
https://www.youtube.com/channel/UC7ia-A8gma8qcdC6GDcjwsQ
"channel/"後方的 UC7ia-A8gma8qcdC6GDcjwsQ 就代表此頻道的 ID。

不過有時會發現網址是呈現以下形式：
https://www.youtube.com/c/六指淵Huber
別擔心，此時隨便點擊頻道底下的其中一支影片，在點中間的頻道名稱進入後，一樣即可看到網址後方的數值。

如何取得頻道 ID

至於"part"需帶什麼數值可以參考官方 API 文檔說明，也可以一個一個嘗試看看會回傳什麼資料。

part 查詢參數

因為請求方式是使用 GET，因此可以直接貼到瀏覽器上測試。
https://www.googleapis.com/youtube/v3/channels?part=contentDetails&id=UC7ia-A8gma8qcdC6GDcjwsQ&key={YOUR_API_KEY}

取得上傳影片清單的 ID

==> 回應資料範例

其中 uploads 後面那串就是此頻道"上傳影片"清單的 ID，這邊是 UU7ia-A8gma8qcdC6GDcjwsQ。

1
2
3
4
5
6
7
8
9


def get_channel_uploads_id(self, channel_id, part='contentDetails'):
"""取得頻道上傳影片清單的ID"""
path = f'channels?part={part}&id={channel_id}'
data = self.get_html_to_json(path)
try:
uploads_id = data['items'][0]['contentDetails']['relatedPlaylists']['uploads']
except KeyError:
uploads_id = None
return uploads_id

取得清單中的影片列表

好的，接下來取得"上傳影片"清單的影片吧~

使用 playlistItems 路徑來取得，需帶上"playlistId"、"key"、"part"等查詢參數。
playlistId 代表播放列表 ID；key 代表我們的 API Key；part 代表想取得的資源屬性。

這邊代的參數大部分與上方雷同，可以自行參考官方 API 文檔說明，就不多說介紹了。
我們要抓此頻道上傳影片，所以 playlistId 帶入上一步抓到的"上傳影片"清單的 ID。

https://www.googleapis.com/youtube/v3/playlistItems?part=contentDetails&playlistId=UU7ia-A8gma8qcdC6GDcjwsQ&key={YOUR_API_KEY}

取得影片ID

==> 回應資料範例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


def get_playlist(self, playlist_id, part='contentDetails', max_results=10):
"""取得影片清單ID中的影片"""
path = f'playlistItems?part={part}&playlistId={playlist_id}&maxResults={max_results}'
data = self.get_html_to_json(path)
if not data:
return []
video_ids = []
for data_item in data['items']:
video_ids.append(data_item['contentDetails']['videoId'])
return video_ids

取得影片資訊

針對每一支影片，來取得其影片相關資訊吧~

使用 videos 路徑來取得，需帶上"id"、"key"、"part"等查詢參數。
id 代表影片 ID；key 代表我們的 API Key；part 代表想取得的資源屬性。

https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=lM7ltxkXE40&key={YOUR_API_KEY}

取得影片資訊

==> 回應資料範例

回傳資料有影片標題、頻道名稱、發布時間、縮圖網址、觀看數、留言數……等等許多相關資訊。

* 謝謝網友提醒，dislikeCount 資訊現在無法取得了，這應該也是因應 YouTube 現在不能看到 Dislike 的數量了。

Note: The statistics.dislikeCount property was made private as of December 13, 2021. This means that the property is included in an API response only if the API request was authenticated by the video owner. See the revision history for more information.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


def get_video(self, video_id, part='snippet,statistics'):
"""取得影片資訊"""
path = f'videos?part={part}&id={video_id}'
data = self.get_html_to_json(path)
if not data:
return {}
# 以下整理並提取需要的資料
data_item = data['items'][0]
try:
time_ = datetime.strptime(data_item['snippet']['publishedAt'], '%Y-%m-%dT%H:%M:%SZ')
except ValueError:
# 日期格式錯誤
time_ = None
url_ = f"https://www.youtube.com/watch?v={data_item['id']}"
info = {
'id': data_item['id'],
'channelTitle': data_item['snippet']['channelTitle'],
'publishedAt': time_,
'video_url': url_,
'title': data_item['snippet']['title'],
'description': data_item['snippet']['description'],
'likeCount': data_item['statistics']['likeCount'],
# 'dislikeCount': data_item['statistics']['dislikeCount'],
'commentCount': data_item['statistics']['commentCount'],
'viewCount': data_item['statistics']['viewCount']
}
return info

取得留言資訊

那該如何取得影片底下的留言呢？

使用 commentThreads 路徑來取得，需帶上"videoId"、"key"、"part"等查詢參數。
videoId 代表播放列表 ID；key 代表我們的 API Key；part 代表想取得的資源屬性。

https://www.googleapis.com/youtube/v3/commentThreads?part=snippet&videoId=lM7ltxkXE40&key={YOUR_API_KEY}

取得留言資訊

==> 回應資料範例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


def get_comments(self, video_id, page_token='', part='snippet', max_results=100):
"""取得影片留言"""
path = f'commentThreads?part={part}&videoId={video_id}&maxResults={max_results}&pageToken={page_token}'
data = self.get_html_to_json(path)
if not data:
return [], ''
# 下一頁的數值
next_page_token = data.get('nextPageToken', '')
# 以下整理並提取需要的資料
comments = []
for data_item in data['items']:
data_item = data_item['snippet']
top_comment = data_item['topLevelComment']
try:
time_ = datetime.strptime(top_comment['snippet']['publishedAt'], '%Y-%m-%dT%H:%M:%SZ')
except ValueError:
# 日期格式錯誤
time_ = None
if 'authorChannelId' in top_comment['snippet']:
ru_id = top_comment['snippet']['authorChannelId']['value']
else:
ru_id = ''
ru_name = top_comment['snippet'].get('authorDisplayName', '')
if not ru_name:
ru_name = ''
comments.append({
'reply_id': top_comment['id'],
'ru_id': ru_id,
'ru_name': ru_name,
'reply_time': time_,
'reply_content': top_comment['snippet']['textOriginal'],
'rm_positive': int(top_comment['snippet']['likeCount']),
'rn_comment': int(data_item['totalReplyCount'])
})
return comments, next_page_token

其他查詢參數

還有其他常用的查詢參數：

像是 maxResults 可以限制回傳筆數，搭配 commentThreads 帶入 maxResults=10 代表最多回傳 10 筆留言。

又例如 pageToken 是用來換頁的，什麼意思呢？
像是 API 有限制留言最多一次只能抓 100 筆留言，就算你帶入 maxResults=200 也只能抓到 100 筆。
但在回傳的資料中可以發現一個 nextPageToken 欄位，代表你再用一樣的網址請求一次，帶上 pageToken=QURTSl9pMmhMYktBc25xOHZtZTg3enJBTFFXNTFPbldJY05zTFFTTjdMM25VYThmdTBwWS1CNGFPZm1kQUU0WkJac0dWZkw3cWI2V1owOA== 就能取得下一頁的資料(例如：101~200 筆留言)。

nextPageToken 欄位

在像是有多個留言(commentThreads)或多支影片(playlistItems)時需要用到。
以上一段取得留言為例，會像是如下：

https://www.googleapis.com/youtube/v3/commentThreads?part=snippet&videoId=lM7ltxkXE40&pageToken=QURTSl9pMmhMYktBc25xOHZtZTg3enJBTFFXNTFPbldJY05zTFFTTjdMM25VYThmdTBwWS1CNGFPZm1kQUU0WkJac0dWZkw3cWI2V1owOA==&key={YOUR_API_KEY}

完整程式碼

附上完整程式碼： youtube_spider_api.py
(對超連結右鍵 > 另存連結為)

注意事項

要注意的是這個 API 有額度的限制，為每天 10,000 個單位( 官方說明 )，如果想將影片的留言都抓下來，可能就會耗費較多額度。
像上方使用的查詢都是消耗 1 單位。

在配額頁面可以查看此專案目前耗費的單位。

配額頁面

延伸練習

在上方教學中，影片清單只有取得前 5 則影片，那如果我想取得前 100 則影片呢？是不是會遇到什麼問題？需不需要加上什麼參數？
* 提示：參考教學中爬取留言的方法，使用 pageToken 參數。
上方教學只說抓取留言，那我如何想取得留言的回覆呢？是要帶入什麼參數嗎？或者是使用不同的方法？
* 提示：part 中的 replies ，或 Comments 資源。

結語

我會陸續寫一些網站的 Python網路爬蟲實例，如果你正好是剛開始想學爬蟲的新手、想知道某個網站如何爬取資料，或者遇到其他問題，歡迎過來參考和在底下留言~👇

參考：
官方 YouTube Data API 範例文檔

每一個成功者都有一個開始。
勇於開始，才能找到成功的路。

爬蟲 Dcard API 2.0 版本？！

jia@jiatool.com (Jia) — Sat, 22 Aug 2020 20:30:00 +0800

前言

目前網路上能查詢到 Dcard 爬蟲的文章，幾乎都是使用www.dcard.tw/_api/這個 API 來抓取。
最近透過開發者工具到發現好像還有 2.0 版本的 API，網路上搜尋不太到什麼資料，不知道是否近期才出來的。

整理

API 網址：https://www.dcard.tw/service/api/v2

說明	請求方法	路徑
全部文章	GET	/posts
看板資訊	GET	/forums
看板內文章列表	GET	/forums/{看板名稱}/posts
文章內文	GET	/posts/{文章ID}
文章內引用連結	GET	/posts/{文章ID}/links
文章內留言	GET	/posts/{文章ID}/comments

全部皆回傳 JSON 格式資料。

* 舊版的只有在 API 網址上不同，其餘的路徑、方法、回傳資料目前觀察起來都一模一樣。
舊版 API 網址：https://www.dcard.tw/_api

API 說明

全部文章

GET https://www.dcard.tw/service/api/v2/posts

取得不分類全部文章，等同於抓取 https://www.dcard.tw/f 頁面內文章資訊。

預設使用 "最新" 作為排序，透過popular參數可以切換 "最新" 與 "熱門"，如下：
最新文章 -> https://www.dcard.tw/service/api/v2/posts?popular=false
熱門文章 -> https://www.dcard.tw/service/api/v2/posts?popular=true

* 但不知為何，有時候不加上參數，資料出來卻不是最新的，還是建議加上popular=false參數較準確。

回傳的文章數量預設是前 30 筆，加上limit參數來限制文章數量，最多 100 筆，如下：
熱門文章前 100 筆 -> https://www.dcard.tw/service/api/v2/posts?popular=true&limit=100

全部文章回傳資料

要取得超過 100 筆文章的方式是加上before參數，例如前一次的路徑是
https://www.dcard.tw/service/api/v2/posts?popular=true
而從回傳的資料中，取得最後一筆其id是234267056，因此下一頁的路徑即是
https://www.dcard.tw/service/api/v2/posts?popular=true&before=234267056

文章網址可透過 https://www.dcard.tw/f/{forumAlias}/p/{id} 組合取得。

看板資訊

GET https://www.dcard.tw/service/api/v2/forums

抓取目前 Dcard 上所有的看板資訊 (包括隱藏的看板!!)。

看板網址可透過 https://www.dcard.tw/f/{alias} 組合取得。

看板內文章列表

GET https://www.dcard.tw/service/api/v2/forums/{看板名稱}/posts

取得指定看板內的文章，等同於抓取 https://www.dcard.tw/f/{看板名稱} 頁面內文章資訊。

預設使用 "最新" 作為排序，透過popular參數可以切換 "最新" 與 "熱門"。

回傳的文章數量預設是前 30 筆，加上limit參數來限制文章數量，最多 100 筆，
而取得下一頁的方式一樣是加上before參數。

文章網址可透過 https://www.dcard.tw/f/{forumAlias}/p/{id} 組合取得。

文章內文

GET https://www.dcard.tw/service/api/v2/posts/{文章ID}

取得指定文章的資訊，等同於抓取 https://www.dcard.tw/f/{看板名稱}/p/{文章ID} 頁面內文章資訊。

有些資訊在文章列表就能抓取到了，但像是"文章完整內容"等資料就需要到此路徑取得。

文章內引用連結

GET https://www.dcard.tw/service/api/v2/posts/{文章ID}/links

取得指定文章內的引用連結，如下圖所示。

文章內引用連結

文章內留言

GET https://www.dcard.tw/service/api/v2/posts/{文章ID}/comments

取得指定文章內的留言。

預設使用 "由舊到新(樓層)" 作為排序，透過popular參數可以切換 "由舊到新" 與 "熱門"。

回傳的文章數量預設是前 30 筆，加上limit參數來限制文章數量，最多 100 筆 (熱門回應只取前3筆)，
而取得下一頁的方式不太一樣，是加上after參數(樓層)，，例如前一次的路徑是
https://www.dcard.tw/service/api/v2/posts/234266517/comments
而從回傳的資料中，取得最後一筆其floor(樓層)是30，因此下一頁的路徑即是
https://www.dcard.tw/service/api/v2/posts/234266517/comments?after=30

文章內留言回傳資料

文章內熱門留言

問題

1. Token is expired. Please refresh the token.

在用瀏覽器測試時，可能會遇到回應 {"error":2007,"message":"Token is expired. Please refresh the token."}，此時只要用無痕模式開啟，或打開 Dcard網頁讓他更新Token，即可解決。

(不確定是 2.0 版本多出的機制，還是原本舊 API 就有了)

2. 請求回傳 403 error (* 2021/01/21 新增)

發現抓不到資料，請求的回傳狀態是 403，但使用瀏覽器卻可以正常取得資料，而且就算 Headers 帶一樣也沒辦法。

將回傳的資料儲存成 html 網頁檔查看：

403錯誤

主要是因為 Dcard 使用了 Cloudflare 的驗證，會需要經過渲染 JavaScript 才能進入。

有幾種方式可以解決，改使用 Selenium 、 Pyppeteer 來模擬瀏覽器操作，或者使用 cloudscraper 專門就是要拿來繞過 Cloudflare 頁面的套件，而且它是建立在 Requests 之上，因此幾乎不用修改程式碼。

如有遇到問題或文章內容有誤，歡迎底下留言告知，感謝~🙂

參考：
Dccard 爬蟲，透過官方API
#99 串接 Dcard API，模仿開發 Dcard App

有一天，或許你會發現，最感動的不是你完成了，
而是你終於鼓起勇氣開始。

—— Peter Su