這個案例將帶領我們模擬真實的網路爬蟲情境，其複雜度比單純的 API 呼叫更高。我們不僅要向外部伺服器請求資料，還要處理其回傳的複雜結構。這份清單聚焦於本案例 Colab 筆記本中實際運用的核心 Python 元件，請各位務必掌握「請求」的標準函式庫，我們將模擬瀏覽器向伺服器發送一個 POST 請求來獲取「動態載入」的資料。

1. requests 函式庫與 HTTP POST 請求

核心概念： requests 是 Python 中用來發送網路請求的關鍵函式庫。在這個案例中，我們使用 requests.post() 來獲取目標網站的留言資料，這是一種常見的動態資料載入方式。

重點說明：

• requests.post(): 許多網頁的內容（例如留言、評論）並不是一開始就寫在 HTML 裡，而是需要透過 POST 請求，主動向伺服器索取。學會 POST 是爬取這類動態網站的關鍵第一步。
• url: (關鍵參數)，這是想要請求數據的網址，通常使用 API 交換數據的網站，網址通常不是你在瀏覽器看到的，網址經常是需要使用 「開發者工具」來找到。這個案例中是一個電商的網址，也是透過開發者工具->Network功能找到的。
• headers: 在發送請求時，我們通常需要附上 headers（標頭），用來模擬一個真實的瀏覽器，告知伺服器我們的身份。缺少正確的 headers 可能會導致請求失敗。
• payload: POST 請求通常會伴隨著一個 payload（負載），也就是我們要傳送給伺服器的資料，用來告訴它我們想要哪一部分的數據（例如：第幾頁的留言）。

你也可參考「Python網路爬蟲 (Web Crawler)」中的 “Requests套件篇”

2. 字典 (dict) 與巢狀字典解析(nested dict parsing)

核心概念： 字典是本案例中處理資料的核心結構。從發送請求的 payload 到解析回傳的 response，都圍繞著字典的操作。

重點說明：

• 建構請求 payload: 我們將 page 參數包裝在一個字典中，作為請求的 payload，精確地告訴伺服器我們需要第幾頁的資料。
• 解析多層巢狀字典: 伺服器回傳的資料是多層嵌套的。我們需要學會如何依序存取字典的 key，例如 data['goodsCommentList']['comments']，才能從複雜的結構中，層層深入，最終定位到包含所有留言的那個列表 (list)。

你也可參考「Python入門與基礎」中的 “資料結構篇”（字典）

3. for 迴圈與列表 (list) 操作

核心概念： 在成功從 JSON 中提取出包含所有留言的列表後，我們利用 for 迴圈來遍歷(iterate)這個列表，逐一處理每一則留言。

重點說明：

「列表生成式」(List Comprehension): 這段程式碼的功能是：從一個比較複雜的資料結構中，快速地建立一個只包含留言文字的、乾淨的新列表。您可以把它想像成一個加工流水線，分成三個步驟來理解：

1. for comment in data["goodsCommentList"] (原料來源)：這部分是流水線的起點。它會先找到一個名為 data 的字典，然後從中取出鍵值為 goodsCommentList 的那個項目，這個項目本身是一個列表 (list)，裡面裝了許多則留言。
2. comment["comment"] (加工動作)：從上一步取出的每一則 comment，它本身可能也是一個字典，裡面包含了留言者、時間、按讚數等多種資訊。這一步的動作是，只從這個 comment 字典中，挑出鍵值為 comment 的那一部分，也就是我們真正想要的「留言文字內容」。
3. comments = [...] (成品裝箱)：最外層的方括號 [] 代表「請幫我建立一個新的列表」。流水線會將每一步加工完成的「留言文字內容」，全部收集起來，放進這個新的列表中。

list.extend(): 我們建立一個名為 all_comments 的空列表，然後在迴圈中，將每一則留言的文字內容 ，逐一加入到這個新列表中，完成資料的萃取與整理。

"".join(): 最後再將這個新列表中的所有字串合併在一起，形成一個長字串。

你也可參考「Python入門與基礎」中的 “流程控制”

4. if else 流程控制

核心概念： 檢查伺服器端的回應是否OK，如果OK代表請求成功，接著就開始處理接收到的資料，如過不成功就發出錯誤訊息。

重點說明：

if response.status_code == 200: (Note: Python 作為比較 “相等” 的運算子為 ==)

• 這一行檢查 HTTP 回應的狀態碼是否等於 200。
• status_code 是 HTTP 回應中的一個重要屬性，表示伺服器回應的結果狀態碼。
• 狀態碼 200 代表 “OK”，表示請求成功並且伺服器成功處理了請求。

data = response.json()

你也可以查詢「HTTP 回應狀態碼」

• 當狀態碼為 200 時，表示請求成功，因此接下來使用 response.json() 方法將伺服器返回的 JSON 格式數據轉換為 Python 字典並賦值給變數 data。
• 這一步是用來處理成功的回應，將 JSON 數據轉換為易於處理的 Python 字典(dict)數據結構。

else:

• 如果回應的狀態碼不是 200（即請求失敗），則執行 else 區塊中的代碼，亦即列印一條錯誤信息，告訴你是哪一頁的請求失敗，並顯示該頁的狀態碼（例如 404 表示找不到頁面，500 表示伺服器錯誤等。

你也可參考「Python入門與基礎」中的 “流程控制”

5. Google Gemini API 的應用

核心概念： 在我們成功爬取並整理好大量的留言文字後，下一步就是從這些非結構化資料中萃取有價值的資訊。這正是 Google Gemini API 發揮作用的地方。我們將整理好的留言列表傳送給 AI，讓它執行複雜的文本分析任務。你要學習如何在colab中儲存 (如果你使用其他AI模型，例如ChatGPT，也是一樣的方法)，然後透過 Gemini 提供的函式來存取金鑰 （userdata.get()），和設定Gemini (config())。

重點說明：

• 化繁為簡： AI 能夠快速閱讀數百則留言，並提煉出「摘要」、「關鍵主題」或「情緒傾向」。這將行銷人員從繁瑣的人工閱讀中解放出來，專注於策略層面。
• 洞察發掘： 透過 AI 分析，我們可以量化消費者的情緒，或發現意想不到的討論熱點，這些都是寶貴的市場洞察。
• 模組化呼叫： 與第一個案例相似，呼叫 AI 的程式碼通常會被封裝在一個獨立的函式中，讓主程式的邏輯更清晰：爬取資料 -> 呼叫AI分析 -> 呈現結果。

總結來說，這個案例的學習路徑是：

requests.post() 發送請求 -> response.json() 解析回傳資料 -> for 迴圈遍歷與萃取 -> 存入 list 整理 -> 轉換成長字串 ->呼叫 AI 分析。

「AI 文案草稿生成」詳解

在學習「AI 文案草稿生成」這個案例時，除了理解整體的行銷應用邏輯外，掌握背後 Python 程式碼的基礎元件也至關重要。這份清單整理了該 Colab 筆記本中最核心的 Python 語法與概念，請確保自己能理解每一個項目的用途。

1. 函式庫匯入與 Colab userdata

核心概念： 程式的第一步，永遠是匯入我們需要用到的工具箱 (函式庫)。

重點說明：

• import json : 引入 json 函式庫來處理 JSON 格式。
• import google.generativeai : 引入 google.generativeai 函式庫來與 Gemini API 互動。
• from google.colab import userdata: 這是 Colab 的一個特有功能，讓我們可以安全地讀取預先儲存的密鑰 (API Key)，避免將敏感資訊直接寫在程式碼中，是程式安全性的重要一環。

2. 錯誤處理 (try / except)

核心概念： try 區塊中的程式碼是我們預期可能發生錯誤的部分。如果 try 區塊真的出錯了，程式不會直接崩潰，而是會跳至 except 區塊執行對應的處理方式。

Python 的 try 可以有多個 except 區塊，這是完全合法且常見的寫法。這樣可以根據不同的例外（Exception）類型採取不同的處理方式。（例如步驟3-5就有兩個except）

重點說明： 網路請求（如呼叫 API）或檔案讀取都可能因為各種原因失敗。使用 try/except 可以優雅地處理這些預期外的狀況（例如 API 金鑰錯誤、網路連線中斷），並給予使用者明確的提示，這是撰寫穩健程式的必備技能。

範例程式碼：

try:
    # 嘗試從 Colab 密鑰管理器中讀取 API 金鑰
    api_key = userdata.get('GEMINI_API_KEY')
    genai.configure(api_key=api_key)
    print("🔑 Gemini API 金鑰已成功設定。")
except Exception as e:
    # 如果發生任何錯誤（例如找不到金鑰），則執行這裡的程式碼
    print(f"🚨 設定 API 金鑰時發生錯誤：{e}")

你也可以參考「Python入門與基礎」的 “例外處理篇”

3. f-String (格式化字串)

核心概念： 一種方便地將變數嵌入字串中的方法(method)。在字串前加上 f，並用大括號 {} 包住變數名稱即可。學習如何動態地組合出最終要傳送給 AI 的指令。

重點說明：

{params.get('axis', '未提供')} 是一個 Python 的 f-string (格式化字串) 語法，裡面嵌入了一個字典(dict)的操作。params 是一個字典 (在這裡是我們在步驟一所定義的變數： marketing_parameters)。

.get('axis', '未提供') 是字典的一個方法，它的作用是：

1. 嘗試從 params 字典中取出鍵 'axis' 所對應的值。
2. 如果找到了 'axis' 這個鍵，就回傳它對應的值 (例如在這個例子中是 “夏日控油大作戰”)。
3. 如果沒有找到 'axis' 這個鍵，就回傳 .get() 方法的第二個參數所指定的值，也就是字串 '未提供'。

將這部分放在 f-string 中，程式執行時就會將這個方法回傳的結果替換掉 {...} 的位置，進而動態地生成包含行銷主軸的提示文字。這樣做的好處是，即使 marketing_parameters 字典中缺少了 'axis' 這個鍵，程式也不會出錯，而是會顯示預設的 '未提供' 字樣，增加了程式的穩健性。

範例程式碼：

def generate_user_prompt(params):
    """根據使用者輸入的參數組合 User Prompt"""
    return f"""
            【品牌與產品核心資訊】
            - 品牌人設：「純淨之鑰 (PureKey)」，專為年輕油性、痘痘肌膚設計的純素保養品牌。

            【行銷策略】
            - 行銷主軸：{params.get('axis', '未提供')}
            - 主打產品：{params.get('product', '未提供')}
            - 目標受眾：{params.get('audience', '未提供')}
            - 內容類型：{params.get('type', '未提供')}
            - 溝通語氣：{params.get('tone', '未提供')}

            請開始生成文案。
            """

你也可以參考「Python進階探索：提升你的程式設計技巧與應用」的 “單元一：字串格式化篇”

4. JSON (JavaScript Object Notation)

核心概念： JSON 是一種輕量級的資料交換格式，因其語法類似 Python 的字典和列表，非常容易閱讀與理解。它由鍵值對（key-value pairs）組成，結構清晰，是現代網路應用中 API 溝通最主流的標準格式。

重點說明：在這個案例中，我們明確要求 AI 以 JSON 格式回傳結果。這確保了 AI 的輸出是結構化的、可預測的，讓我們的 Python 程式能穩定地解析與使用這些資料，而不是處理一段格式混亂的文字。

範例格式： 這就是一個 JSON 格式的範例，它是一個列表 ([])，裡面包含了三個字典 ({})。

[
  {
    "platform": "Instagram",
    "copy": "IG文案...",
    "hashtags": "#..."
  },
  {
    "platform": "Dcard",
    "copy": "Dcard文案...",
    "hashtags": "#..."
  },
  {
    "platform": "Facebook",
    "copy": "FB文案...",
    "hashtags": "#..."
  }
]

你也可參考「Python網路爬蟲 (Web Crawler)」中的 “使用API(JSON)篇”

5. 變數與資料類型 (Variables & Data Types)

核心概念： 變數是儲存資料的容器。在這個案例中，我們主要使用了 字串 (string) 來存放提示詞文本，以及 字典 (dictionary) 來結構化地組織行銷參數。

• 字串 (str): 所有與 AI 溝通的提示詞都是文字，是 NLP 應用的基礎。被 ” ” 或是 ‘ ‘ 符號刮起來的文字就是字串。
• 多行字串 """...""": 我們使用三個引號來建立包含複雜內容的系統提示詞 (System Prompt) 和用戶提示詞(User Prompt)。

多行字串範例程式碼：

SYSTEM_PROMPT = """
你是一位頂尖的新創美妝品牌社群行銷專家
你正在為品牌「純淨之鑰」規劃給 Instagram, Dcard, Facebook 的社群內容。
...

"""

• 字典 (dict): 使用 key: value 的形式，能讓我們用有意義的名稱（如 "axis"）來存取對應的資料 (如 "夏日控油大作戰"），使程式碼更具可讀性，也方便未來擴充。

字典範例程式碼：

# 使用字典來組織行銷活動的所有參數
marketing_parameters = {
    'axis': "夏日控油大作戰",
    'product': "茶樹淨痘精華液",
    'audience': "18-25歲，深受粉刺痘痘困擾的大學生與社會新鮮人",
    'type': "新品上市優惠",
    'tone': "有活力、像學姊一樣親切分享"
}

你也可參考「Python入門與基礎」中的 “變數” & “資料結構篇”(字典)

6. 自訂函式 (Defining Functions with def)

核心概念： 使用 def 關鍵字可以將一段特定的程式碼打包成一個可重複使用的功能區塊，稱為函式。我們可以為它命名，並定義它需要接收的輸入（參數）和回傳的輸出。

重點說明： 將「呼叫 AI 並解析結果」的邏輯封裝成一個函式，可以讓主程式更簡潔。未來若要針對不同目的呼叫 AI，可以直接重複使用此函式，而無需複製貼上相同的程式碼，大大提升了程式的模組化與維護性。

範例程式碼：

# 定義一個函式，專門用來呼叫 AI 並回傳結果
def generate_user_prompt(params):
    """根據使用者輸入的參數組合 User Prompt"""
    return f"""
           ....
           請開始生成文案
           """

你也可參考「Python入門與基礎」中的 “函式篇”

7. Google Gemini API 的應用：生成文案

核心概念： 這是實際與 AI 互動、執行「根據提示詞生成 JSON 格式文案」任務的關鍵步驟。我們需要初始化模型，並呼叫它的方法來發送組合好的提示詞。

重點說明：

• genai.GenerativeModel(...): 使用這段程式碼來初始化我們要使用的 Gemini 模型。
• model.generate_content(...): 這是執行生成任務的核心函式。我們將組合好的 system_prompt 和 user_prompt 作為參數傳給它，它會將請求發送給 Google 的伺服器，並等待 AI 的回應。真實可以操作的列表與字典物件。

你也可參考「提示工程：5 steps to design better prompts with RACES」了解如何設計一個好的提示詞(prompt)

Open AI Academy 也提供 Prompt Engineering教學：「Introduction」「Advanced」

8. 流程控制 (for 迴圈)

核心概念： for 迴圈可以讓我們遍歷一個序列（例如一個 list 列表）中的每一個項目，並對其執行相同的操作。

重點說明： AI 模型一次回傳了三個平台（Instagram, Dcard, Facebook）的文案，這些結果被存放在一個列表中。我們使用 for 迴圈，可以依序取出每一筆平台的資料（一個字典），並將其內容整齊地印出，省去了手動存取三次的麻煩。

範例程式碼：

# copy_data 是一個包含多個字典的列表 [{"platform": "Instagram", ...}, {"platform": "Dcard", ...}]
for item in copy_data:
    print("="*50)
    print(f"平台: {item['platform']}")
    print("="*50)
    print("【文案內容】")
    print(item['copy'])
    ...

你也可參考「Python入門與基礎」中的 “流程控制篇”