# فصل ۶ — JSON و کلید API: زبان داده‌ها و کلیدِ درها

<div dir="rtl">

# فصل ۶ — JSON و کلید API: زبان داده‌ها و کلیدِ درها

## در این فصل چه می‌سازی

هر سفری دو چیز می‌خواهد: زبانِ آن سرزمین، و کلیدِ درهایش. فصلِ بعد پروژهٔ تو برای اولین بار با یک **هوش مصنوعیِ واقعی** حرف می‌زند — و امروز هر دو چیزِ لازم برای این سفر را برمی‌داری. اول **زبان**: سرویس‌های بزرگِ اینترنت، از هواشناسی تا Gemini، همه به یک زبانِ مشترک جواب می‌دهند به اسم **JSON** (راستش را بخواهی، فصل ۲ که زمانِ جهانی را گرفتی، آن متنِ پر از آکولاد و دونقطه JSON بود!). دوم **کلید**: درِ سرویس‌های بزرگ با یک رمزِ شخصی به اسم API key باز می‌شود — و رمز، جای امن می‌خواهد. آخرِ فصل، خانهٔ امنی به اسم `secrets.py` می‌سازی و بالاخره پسوردِ WiFi را از وسطِ کد جمع می‌کنی. و پروژهٔ امروز بامزه است: ایستگاه هواشناسیِ ترم ۲ که دمای اتاقت را می‌گفت، امروز **جهانی** می‌شود — دمای همین لحظهٔ توکیو، روی OLED روی میزِ تو!

آخر این فصل می‌توانی:

- دیکشنری کامل بسازی و بخوانی: خواندن با کلید، تغییرِ مقدار، افزودنِ کلید، و ساختارِ تودرتو (دیکشنری در دیکشنری، لیست در دیکشنری).
- با `json.dumps` و `json.loads` بین رشته و دیکشنری رفت‌وبرگشت کنی و قواعدِ سخت‌گیرانهٔ JSON را بگویی.
- پاسخِ JSON یک سرویسِ واقعی را با کلیدزنیِ تودرتو بخوانی و روی OLED نشان بدهی.
- بگویی API key چیست (مثلِ رمزِ عبور) و rate limit یعنی چه.
- فایلِ `secrets.py` بسازی و توضیح بدهی چرا رمزها هرگز در کدِ اشتراکی نمی‌مانند.

## قبل از شروع: چک‌لیست پیش‌نیاز

قبل از ادامه این‌ها را چک کن — اگر یکی‌شان لنگ می‌زند، اول برگرد همان فصل:

- **از فصل ۲:** ماژول `urequests`، درخواستِ GET و خواندنِ مقدار با `data["key"]` — امروز دیکشنری را کامل می‌کنیم.
- **از فصل ۱:** اتصال WiFi — و ادای قولِ همان فصل: پسورد به خانهٔ امن می‌رود.
- **از فصل ۳:** رشتهٔ سه‌نقل‌قولی — برای JSONهای دست‌سازِ تمرینی.
- **از ترم ۳، فصل ۳:** ساخت و `import` ماژولِ خودمان (`robot.py`) — `secrets.py` هم دقیقاً همین‌طور کار می‌کند.
- **از ترم ۲، فصل ۵ و ۷:** لیست و index + نمایشگر OLED با کتابخانهٔ `ssd1306`.

لوازم این فصل:

| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| ESP32 + Breadboard + کابل USB | ۱ | — |
| OLED 0.96 اینچ I2C (کیت ترم ۲) | ۱ | بدونِ OLED هم می‌شود — خروجی در Shell |
| WiFi خانگی ۲.۴ گیگاهرتز | — | هات‌اسپاتِ گوشی |
| کامپیوتر با Thonny و کابل USB | ۱ | — |

> 🧪 **آزمایشگاه:** زمین بازیِ دیکشنری (فایلِ ۱) شبکه نمی‌خواهد و در آزمایشگاه اجرا می‌شود؛ ولی نسخهٔ هواشناسی به WiFi واقعی احتیاج دارد و در شبیه‌ساز کار نمی‌کند — کدش را همان‌جا ببین و کپی کن تا تایپ‌نکرده جلو بروی. [برو به آزمایشگاه](/lab).

## ۱. دیکشنری: قفسه‌ای با کشوهای اسم‌دار

از ترم ۲ لیست را داری: یک قفسه با کشوهای **شماره‌دار** — `notes[0]`، `notes[1]`. لیست عالی است وقتی ترتیب مهم است. ولی فرض کن می‌خواهی مشخصاتِ رباتت را نگه داری: اسم، سرعت، رنگ. «اسم» که شماره ندارد! اینجا **دیکشنری** می‌آید: قفسه‌ای با کشوهای **اسم‌دار**. روی هر کشو یک برچسب — به برچسب می‌گوییم **کلید** (key) و به محتوای کشو **مقدار** (value). فصل ۲ فقط یاد گرفتی کشو را باز کنی (`data["key"]`)؛ امروز کلِ قفسه مالِ توست. Shell را باز کن و با من بساز:

</div>

```python
>>> me = {"name": "AIRO", "speed": 600, "online": True}
>>> me["name"]
'AIRO'
>>> me["speed"] = 650        # avaz kardan-e meghdar-e yek keshoo
>>> me["color"] = "abi"      # keshoo-ye jadid ba yek khat!
>>> me
{'name': 'AIRO', 'speed': 650, 'online': True, 'color': 'abi'}
```

<div dir="rtl">

قواعدش را ببین: آکولادِ باز، جفت‌های «کلید دونقطه مقدار» با کاما، آکولادِ بسته. خواندن و نوشتن، هر دو با `["کلید"]` — اگر کلید باشد مقدارش عوض می‌شود، نباشد ساخته می‌شود.

> 💡 **نکته:** ممکن است کشوها روی بردِ تو با **ترتیبِ دیگری** چاپ شوند. اشکالی ندارد و برد خراب نیست: لیست ترتیب دارد، دیکشنری ندارد. در دیکشنری فقط برچسب‌ها مهم‌اند، نه اینکه کدام اول نوشته شده — پس هیچ‌وقت به ترتیبِ کشوها تکیه نکن.

✅ **چک کن:** با `print(me)` قفسه‌ات را ببین. باید چهار کشو داشته باشد: `name`، `speed` (که حالا ۶۵۰ است)، `online` و کشوی تازهٔ `color`.

## ۲. ساختارِ تودرتو: قفسه در قفسه

مقدارِ یک کشو هر چیزی می‌تواند باشد: رشته، عدد، بولی — و حتی یک دیکشنریِ دیگر! اینجاست که قدرتِ واقعی معلوم می‌شود:

</div>

```python
>>> robot_info = {
...     "name": "AIRO",
...     "battery": {"volt": 7.4, "percent": 80},
...     "sensors": ["DHT11", "LDR", "HC-SR04"],
... }
>>> robot_info["battery"]["percent"]
80
>>> robot_info["sensors"][0]
'DHT11'
```

<div dir="rtl">

به این می‌گوییم ساختارِ **تودرتو** (nested): داخلِ کشوی `battery` یک قفسهٔ کوچک‌تر است! برای رسیدن به درصدِ شارژ، دو بار کشو باز می‌کنیم: اول `["battery"]`، بعد `["percent"]` — از چپ به راست، لایه‌به‌لایه. و کشوی `sensors` یک **لیست** دارد؛ پس اول با کلید بازش می‌کنیم، بعد با index شماره‌دارِ ترم ۲: `[0]`.

![قفسهٔ تودرتوی JSON: قفسهٔ بزرگی با عنوان robot_info و سه کشوی name و battery و sensors؛ کشوی battery باز است و داخلش قفسهٔ کوچک‌تری با دو کشوی volt و percent دیده می‌شود، و کشوی sensors یک جای‌چیپیِ شماره‌دار با برچسب‌های DHT11 و LDR و HC-SR04 دارد؛ یک مسیرِ نقطه‌چین با دو کلید، دو قدمِ رسیدن به percent را نشان می‌دهد](/lesson-assets/t4-s06-json-apikeys/prompt/01-image-json-tree.png)

ترکیبِ دیکشنری و لیست، اسکلتِ تقریباً همهٔ داده‌های اینترنت است — و پاسخِ Gemini در فصل ۷ هم دقیقاً همین شکلی است.

## چالش: چطور به "LDR" برسی؟

از همان `robot_info` بالا، برای بیرون‌کشیدنِ `"LDR"` چه می‌نویسی؟ (دو قدم دارد!)

---

**جواب:** اول کشوی `sensors` را باز کن، بعد عضوِ شمارهٔ یکِ لیست را بردار: `robot_info["sensors"][1]`. کلیدِ `sensors` تو را به لیست می‌رساند و index شمارهٔ ۱ عضوِ دومِ لیست — یعنی `"LDR"` — را می‌دهد (چون شمارش از صفر شروع می‌شود).

## ۳. ماژول json: مترجمِ دوطرفه

دیکشنری مالِ Python است و داخلِ حافظهٔ برد زندگی می‌کند. ولی وقتی داده می‌خواهد **سفر** کند — از سرویسِ هواشناسی به بردِ تو، یا از بردِ تو به Gemini — باید تبدیل به **متن** شود، چون شبکه فقط متن جابه‌جا می‌کند. JSON دقیقاً همین است: «دیکشنریِ متن‌شده» با قواعدِ جهانی، تا هر زبانِ برنامه‌نویسی در هر گوشهٔ دنیا بفهمدش. MicroPython یک مترجمِ رسمی دارد: ماژولِ `json` با دو فعلِ مهم. `dumps` یعنی «دیکشنری را بریز بیرون به شکلِ رشته» و `loads` یعنی «رشته را بار کن به شکلِ دیکشنری»:

</div>

```python
>>> import json
>>> text = json.dumps(me)
>>> text
'{"name": "AIRO", "speed": 650, "online": true, "color": "abi"}'
```

<div dir="rtl">

دو چیزِ عجیب می‌بینی؟ اول اینکه همهٔ کوتیشن‌ها **دابل** شدند، و دوم `True`ی بزرگِ Python شده `true`ی کوچک! این‌ها قواعدِ JSON هستند، نه سلیقه: در JSON کوتیشن فقط دابل است و true/false کوچک نوشته می‌شوند. حالا برای برگشت، مترجم را برعکس صدا می‌زنیم — و بگذار عمداً یک اشتباهِ رایج هم بکنیم: JSON دست‌ساز را با کوتیشنِ تکی بنویسیم، همان‌طور که در Python عادت داریم:

</div>

```python
>>> data = json.loads("{'temp': 24, 'hum': 41}")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: syntax error in JSON
```

<div dir="rtl">

`ValueError: syntax error in JSON` — این خطا را خوب به خاطر بسپار، چون در دنیای API زیاد می‌بینی‌اش. مترجمِ JSON سخت‌گیر است: کوتیشنِ تکی؟ رد. متنی که اصلاً JSON نیست (مثلاً صفحهٔ خطای HTML)؟ رد. کامای اضافه در انتها هم در JSON غلط است و Python کامپیوتر ردش می‌کند، ولی `json` روی برد از آن می‌گذرد؛ پس هرگز به این چشم‌پوشی تکیه نکن. اصلاحش کن — کوتیشن‌ها را دابل بگذار:

</div>

```python
>>> data = json.loads('{"temp": 24, "hum": 41}')
>>> data["temp"] + 1
25
```

<div dir="rtl">

ببین چه شد: تا یک لحظه پیش `"24"` وسطِ یک متنِ مرده بود؛ الان `data["temp"]` یک **عددِ زنده** است که می‌شود با آن حساب کرد. این جادوی `loads` است. و یک اتصالِ قشنگ به گذشته: `r.json()` که از فصل ۲ استفاده می‌کنی، دقیقاً همین `json.loads` است که urequests از سرِ لطف خودش برایت صدا می‌زند! کدِ کاملِ زمین بازیِ امروز — دیکشنری و json کنارِ هم — در `01_json_playground.py` است:

</div>

```python
# Term 4 - Session 06 - zamin-e bazi: dictionary-e kamel + module-ye json
import json

# --- 1) sakht-e dictionary: shenasname-ye robot-e ma ---
me = {"name": "AIRO", "speed": 600, "online": True}
print(me["name"])            # khandan ba kelid
me["speed"] = 650            # avaz kardan-e meghdar
me["color"] = "abi"          # keshoo-ye jadid ba yek khat
print(me)

# --- 2) dumps: dictionary -> reshte-ye JSON (baraye ferestadan) ---
text = json.dumps(me)
print(text)                  # deghat: quote-ha double shodand, True shod true!

# --- 3) loads: reshte-ye JSON -> dictionary (baraye fahmidan) ---
data = json.loads('{"temp": 24, "hum": 41}')
print(data["temp"] + 1)      # alan adad-e zende ast: 25

# --- 4) sakhtar-e tu-dar-tu: dictionary dar dictionary + list dar dictionary ---
robot_json = """{
  "name": "AIRO",
  "battery": {"volt": 7.4, "percent": 80},
  "sensors": ["DHT11", "LDR", "HC-SR04"]
}"""
info = json.loads(robot_json)
print(info["battery"]["percent"])   # do bar keshoo baz kon: 80
print(info["sensors"][0])           # kelid + index-e list: DHT11
```

<div dir="rtl">

## چالش: dumps یا loads؟

`dumps` چه می‌گیرد و چه می‌دهد؟ `loads` چطور؟ و کدام‌یک موقعِ **فرستادنِ** داده به یک سرویس به کار می‌آید؟

---

**جواب:** `dumps` یک دیکشنری می‌گیرد و یک **رشتهٔ** JSON می‌دهد؛ `loads` یک رشتهٔ JSON می‌گیرد و یک **دیکشنری** می‌دهد. موقعِ فرستادن، `dumps` به کار می‌آید — چون شبکه فقط متن جابه‌جا می‌کند، پس داده را اول باید به رشته «متن‌شده» تبدیل کنی. (`loads` برای فهمیدنِ جوابی است که برمی‌گردد.)

## ۴. پروژه: ایستگاه هواشناسیِ جهانی

وقتِ پروژه است. یک سرویسِ هواشناسیِ رایگان و بدونِ ثبت‌نام هست که آب‌وهوای هر نقطهٔ زمین را JSON می‌دهد — اسمش Open-Meteo است و نشانی‌اش در کدِ پایین آمده است (سرویس‌ها به‌روز می‌شوند، پس اگر روزی جواب نداد، نشانیِ تازه را در سایتِ خودِ Open-Meteo پیدا کن). فقط مختصاتِ شهر را در پارامترهایش می‌گذاری؛ برای شروع توکیو گذاشته‌ایم و مختصاتِ هر شهری را از اپِ نقشهٔ گوشی درمی‌آوری. درخواستِ GET را مثلِ فصل ۲ می‌فرستیم و با اعتمادبه‌نفس دما را می‌خوانیم:

</div>

```python
r = urequests.get(URL)
data = r.json()
r.close()
print(data["temperature"])
```

<div dir="rtl">

اجرا و...

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
KeyError: temperature
```

<div dir="rtl">

`KeyError` یعنی «کشویی با این برچسب پیدا نکردم». ولی مطمئنیم دما آنجاست! قانونِ کارآگاهیِ JSON را یاد بگیر — قدمِ اول همیشه: **کلِ نقشه را چاپ کن.** یک `print(data)` بزن:

</div>

```text
{'latitude': 35.7, 'longitude': 139.7, 'current_weather': {'temperature': 18.3,
'windspeed': 8.2, 'winddirection': 245, 'is_day': 1}, ...}
```

<div dir="rtl">

آهان! دما در طبقهٔ اول نیست — داخلِ کشوی `current_weather` است: ساختارِ تودرتو، دقیقاً همان که اولِ فصل تمرین کردیم! پس دو قدم: اول `["current_weather"]`، بعد `["temperature"]`. و همین‌جا درسِ اصلی را قاب کن: نقشه‌ای که بالا چاپ شده نقشهٔ **همین سرویس در همین لحظه** است، نه یک قانونِ ابدی — سرویس‌ها ساختارِ پاسخشان را عوض می‌کنند. پس هر بار که سراغِ یک سرویسِ تازه می‌روی، اول `print(data)`، بعد کلیدزنی. حالا کدِ کامل با OLED، که قالبش را از ایستگاه هواشناسیِ ترم ۲ قرض می‌گیریم (فایلِ `02_world_weather.py`):

</div>

```python
# Term 4 - Session 06 - havashenasi-e jahani rooye OLED (noskhe-ye dars)
# URL-e service: gahi avaz mishavad
from machine import Pin, I2C
import network
import urequests
import ssd1306
import time

WIFI_SSID = "esm-e-wifi-khodet"
WIFI_PASS = "password-e-wifi"

# mokhtasat-e Tokyo - mokhtasat-e shahr-e khodet ra az app-e naghshe bardar
URL = "https://api.open-meteo.com/v1/forecast?latitude=35.7&longitude=139.7&current_weather=true"

i2c = I2C(0, scl=Pin(22), sda=Pin(21))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect(WIFI_SSID, WIFI_PASS)
print("dar hal-e ettesal be WiFi...")
tries = 0
while not wlan.isconnected() and tries < 15:
    time.sleep(1)
    tries = tries + 1
if wlan.isconnected():
    print("vasl shod! IP:", wlan.ifconfig()[0])
else:
    print("vasl nashod - WiFi ra ba code-haye jalase 1 check kon")

print("gereftan-e ab-o-hava...")
r = urequests.get(URL)
data = r.json()      # javab-e JSON -> dictionary (haman json.loads-e makhfi!)
r.close()            # azad kardan-e hafeze - hamishe!

weather = data["current_weather"]    # ghadam-e 1: keshoo-ye tu-dar-tu
temp = weather["temperature"]        # ghadam-e 2: khod-e adad
wind = weather["windspeed"]
print(f"Temp: {temp} C | Wind: {wind} km/h")

oled.fill(0)
oled.text("TOKYO WEATHER", 0, 0)
oled.text(f"TEMP: {temp} C", 0, 20)
oled.text(f"WIND: {wind}", 0, 35)
oled.show()
```

<div dir="rtl">

✅ **چک کن:** روی OLED باید دمای زندهٔ توکیو را ببینی. دمای توکیو را در مرورگر جست‌وجو کن: عددش نزدیک است، هرچند سایت‌های هواشناسی با هم کمی فرق دارند! این عدد همین لحظه از آن‌طرفِ کرهٔ زمین آمده و از دلِ JSON، با دو کلیدزنی، بیرون کشیده شده. ایستگاهِ ترم ۲ دماسنجِ اتاقت بود؛ این یکی چشمش به کلِ سیاره است.

> 🔧 **اگر کار نکرد:** `KeyError` گرفتی روی یک کلیدِ دیگر؟ قانونِ کارآگاه: اول `print(data)` بزن، نقشه را ببین و لایه‌به‌لایه کلید بزن. اگر موقعِ `urequests.get` خطای `OSError` گرفتی، WiFi وصل نیست یا اینترنت قطع است: اول `wlan.isconnected()` را چک کن و URL را حرف‌به‌حرف با کدِ همین فصل مقایسه کن. و `r.close()` را هرگز فراموش نکن، وگرنه حافظهٔ برد پر می‌شود.

## چالش: با KeyError چه می‌کنی؟

اگر `KeyError` گرفتی ولی مطمئنی داده رسیده، اولین حرکتِ کارآگاهی چیست؟

---

**جواب:** کلِ نقشه را چاپ کن: `print(data)`. با دیدنِ ساختارِ واقعی می‌فهمی کلیدِ موردِ نظرت کجاست — معمولاً یک لایه پایین‌تر، داخلِ یک کشوی تودرتو — و بعد لایه‌به‌لایه به آن می‌رسی. هیچ‌وقت کورکورانه کلید نزن؛ اول نقشه، بعد مسیر.

## ۵. کلید API و rate limit

سرویسِ امروز در نگاهِ اول عجیب بود: نه ثبت‌نامی، نه رمزی. ولی سرویس‌های بزرگ‌تر — مثلِ Gemini که فصلِ بعد سراغش می‌رویم — درِشان قفل است و برای ورود یک **API key** می‌خواهند: یک رشتهٔ طولانی از حرف و عدد که سرویس فقط به تو می‌دهد. مثلِ چی؟ **مثلِ رمزِ عبور.** همان‌قدر شخصی، همان‌قدر حساس. کلید دو کار می‌کند: به سرویس می‌گوید این درخواست از طرفِ کیست، و چقدر از سهمیه‌اش را مصرف کرده.

![کلید API مثلِ رمزِ عبور: کارتی درخشان با کدی ماسک‌شده در دستِ یک نوجوان، جلوی دروازهٔ یک سرویسِ ابری با سوراخِ کلید؛ اسکنرِ دروازه دو نشانگر دارد با برچسب «کیست؟» و «چقدر مصرف کرده؟»؛ کنارش سه آیکونِ قرمزِ خط‌خورده: فرستادن کارت در گروهِ چت، گذاشتنش در یک صفحهٔ کدِ عمومی، و چاپش در اسکرین‌شات](/lesson-assets/t4-s06-json-apikeys/prompt/03-image-apikey-card.png)

و همین‌جا مفهومِ دوم می‌آید: **rate limit** یعنی سقفِ مصرف — مثلِ کارتِ بوفهٔ مدرسه که روزی چند بار بیشتر کار نمی‌کند. چرا سرویس‌ها سقف می‌گذارند؟ چون کامپیوترهایشان بینِ میلیون‌ها نفر مشترک است؛ سقف یعنی سهمِ منصفانه برای همه. اگر برنامه‌ات در یک حلقهٔ تند و بی‌وقفه درخواست بزند، سهمت زود تمام می‌شود. قانونِ مؤدب‌بودن ساده است: **فقط وقتی بپرس که واقعاً لازم داری.** برای آب‌وهوا، هر ده دقیقه یک بار هم زیادی است!

![rate limit مثلِ کارتِ بوفهٔ مدرسه: یک پیشخوانِ سرو با برچسبِ «سرویسِ ابری»، جلویش یک گیتِ چرخانِ «rate limit»؛ صفی از ربات‌های کوچک هرکدام با کارتِ منگنه‌ایِ «سهمیهٔ روزانه»؛ یک رباتِ مؤدب با تیکِ سبز رد می‌شود و رباتِ حریصی که چرخ‌دستیِ پر از درخواست دارد با علامتِ ملایمِ «خنک شو» متوقف می‌شود؛ بالای صحنه بنری با نوشتهٔ «سهمِ منصفانه برای همه»](/lesson-assets/t4-s06-json-apikeys/prompt/05-image-rate-limit.png)

## ۶. خانهٔ امن: secrets.py

حالا مهم‌ترین درسِ امنیتیِ دوره. رمز — چه پسوردِ WiFi چه API key — **هرگز وسطِ کد نمی‌ماند.** چرا؟ چون کد جای نمایش است: به دوستت نشانش می‌دهی، در گروه می‌فرستی تا کمکت کنند، در گالریِ عمومیِ آزمایشگاه می‌گذاری، شاید روزی هم در گیت‌هاب منتشرش کنی. هر بار، رمزت هم جلوی چشمِ همه است!

راه‌حلِ حرفه‌ای‌ها ساده و قشنگ است: **رمزها به یک فایلِ جدا می‌روند، و آن یک فایل هرگز جایی نمی‌رود.** از ترم ۳ بلدی ماژولِ خودت را بسازی — `robot.py` یادت هست؟ حالا یک ماژول می‌سازیم به اسمِ `secrets.py`، یعنی «رازها»:

</div>

```python
# secrets.py - hame-ye ramz-haye project inja hastand
# IN FILE RA BA HICHKAS SHARE NAKON! na git, na Wokwi-e umumi, na screenshot!

WIFI_SSID = "esm-e-wifi-khodet"
WIFI_PASS = "password-e-wifi"

# jalase 7: kelid-e Gemini API ham inja ezafe mishavad
```

<div dir="rtl">

![دو نیمهٔ بهداشتِ رمز: سمت چپ یک فایلِ کدِ بازِ دوستانه با برچسبِ main.py روی یک سکوی روشن و نشانِ سبزِ «اشتراکش اشکالی ندارد» و خطِ import secrets بدونِ هیچ رمزی؛ سمت راست یک فایلِ کوچکِ گاوصندوق‌شکل با برچسبِ secrets.py و قفلِ رمزی که کارت‌های «پسورد WiFi» و «کلید API» را نگه داشته و نشانِ قرمزِ «هرگز به اشتراک نگذار»؛ زیرِ گاوصندوق سه مقصدِ خط‌خورده: گیت، پروژهٔ عمومیِ شبیه‌ساز، گروهِ چت](/lesson-assets/t4-s06-json-apikeys/prompt/04-image-secrets-vault.png)

فایل را با نامِ `secrets.py` روی برد ذخیره کن — و در کدِ اصلی، به‌جای رمزِ لخت، از ماژول بخوان. یادت هست فصل ۱ گفتیم «فعلاً پسورد را همین‌جا بنویس؛ بعداً جای امنی برایش می‌سازیم»؟ امروز آن قول ادا می‌شود:

</div>

```python
import secrets

wlan.connect(secrets.WIFI_SSID, secrets.WIFI_PASS)
```

<div dir="rtl">

اجرا... و اگر کار نکرد، احتمالاً این خطا را می‌بینی:

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 5, in <module>
ImportError: no module named 'secrets'
```

<div dir="rtl">

`ImportError` — همان آشنای فصل قبل: «فایلی به این اسم روی برد نیست». ولی همین الان ذخیره‌اش کردی! به لیستِ فایل‌های برد در Thonny نگاه کن... آهان: `secret.py` — بدونِ s آخر! تایپِ اشتباهِ اسمِ فایل، رایج‌ترین دلیلِ این خطاست: `import secrets` دنبالِ فایلی می‌گردد که **دقیقاً** `secrets.py` باشد. اسمش را درست کن، دوباره اجرا — وصل شد. نسخهٔ نهاییِ ایستگاه که هر ده دقیقه مؤدبانه به‌روز می‌شود، در `03_world_weather_secrets.py` است:

</div>

```python
# Term 4 - Session 06 - noskhe-ye nahayi: secrets.py + update-e moadab (rate limit!)
# ghabl az ejra: secrets.py bayad ba meghdar-haye vaghei rooye bord bashad
from machine import Pin, I2C
import network
import urequests
import ssd1306
import secrets
import time

# mokhtasat-e Tokyo - mokhtasat-e shahr-e khodet ra az app-e naghshe bardar
URL = "https://api.open-meteo.com/v1/forecast?latitude=35.7&longitude=139.7&current_weather=true"
UPDATE_SECONDS = 600   # har 10 daghighe yek bar - be rate limit ehteram bogzar!

i2c = I2C(0, scl=Pin(22), sda=Pin(21))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect(secrets.WIFI_SSID, secrets.WIFI_PASS)   # ramz az khane-ye amn
print("dar hal-e ettesal be WiFi...")
tries = 0
while not wlan.isconnected() and tries < 15:
    time.sleep(1)
    tries = tries + 1
if wlan.isconnected():
    print("vasl shod! IP:", wlan.ifconfig()[0])
else:
    print("vasl nashod - WiFi ra ba code-haye jalase 1 check kon")

while True:
    try:
        r = urequests.get(URL)
        data = r.json()
        r.close()
        weather = data["current_weather"]
        temp = weather["temperature"]
        wind = weather["windspeed"]
        print(f"Temp: {temp} C | Wind: {wind} km/h")
        oled.fill(0)
        oled.text("WORLD WEATHER", 0, 0)
        oled.text(f"TEMP: {temp} C", 0, 20)
        oled.text(f"WIND: {wind}", 0, 35)
        oled.show()
    except OSError:
        print("khata dar ettesal! update-e ba'di ra emtehan mikonam")
        oled.fill(0)
        oled.text("NET ERROR!", 0, 20)
        oled.show()
    time.sleep(UPDATE_SECONDS)
```

<div dir="rtl">

حالا کدِ اصلیِ تو **قابلِ نمایش** است: هر که ببیندش، فقط `secrets.WIFI_PASS` می‌بیند، نه خودِ رمز را.

> ⚠️ **مواظب باش:** اگر روزی رمز یا کلیدت را اشتباهی جایی فرستادی، مثلِ رمزِ عبورِ لورفته رفتار کن: همان لحظه در سایتِ سرویس باطل/عوضش کن، و پسوردِ WiFi را از تنظیماتِ روتر عوض کن. لورفتن مشکلی است که با یک کلیدِ نو حل می‌شود — به‌شرطی که به‌موقع بفهمی‌اش.

## چالش: کجا secrets.py «هرگز» نباید دیده شود؟

سه جایی که رمزهایت هرگز نباید بروند کجاست؟

---

**جواب:** سه جایِ خطرناک: (۱) گیت و مخزنِ عمومیِ کد (مثلِ گیت‌هاب)، (۲) پروژهٔ عمومی در گالریِ آزمایشگاه یا هر شبیه‌سازِ اشتراکیِ دیگر، و (۳) اسکرین‌شات و عکس و ویدیو از صفحه‌ات. در هر سه، `secrets.py` و محتوایش پیشِ کسانی می‌رود که نباید. کدت را با خیال راحت نشان بده — ولی `secrets.py` می‌ماند پیشِ خودت.

## واژه‌های تازه این فصل

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| JSON | جِی‌سان | زبانِ مشترکِ داده در اینترنت؛ «دیکشنریِ متن‌شده» |
| Key | کی | کلید؛ برچسبِ کشوی دیکشنری |
| Value | وَلیو | مقدار؛ محتوای کشو |
| Nested | نِستِد | تودرتو؛ قفسه‌ای داخلِ یک کشو |
| Parse | پارس | تجزیهٔ متن به دادهٔ قابلِ‌استفاده — کاری که `loads` می‌کند |
| API key | اِی‌پی‌آی کی | رمزِ شخصیِ ورود به یک سرویس — مثلِ رمزِ عبور |
| Rate limit | رِیت لیمیت | سقفِ مصرف؛ سهمِ منصفانهٔ هر کاربر از سرویس |
| Secret | سیکرِت | راز؛ هر چیزی که در `secrets.py` می‌ماند و جایی نمی‌رود |

## تمرین‌ها

اول چک‌لیستِ پایانِ فصل: یک دیکشنریِ تودرتو می‌سازی و با کلیدزنیِ دومرحله‌ای و index لیست مقدارِ درست را بیرون می‌کشی؛ فرقِ `dumps` و `loads` را می‌دانی و می‌دانی `r.json()` همان `loads` است؛ ایستگاه هواشناسیِ جهانی دمای زندهٔ یک شهر را روی OLED نشان می‌دهد؛ و `secrets.py` روی بردت است و کدِ اصلی هیچ رمزِ لختی ندارد. اگر همه بله است، برو سراغ تمرین‌ها:

- **تمرین اجباری:** ایستگاه هواشناسیِ جهانی را با `secrets.py` و مختصاتِ شهرِ خودت (یا شهری که دوستش داری — پاریس؟ سیدنی؟) راه بینداز (`my_weather.py`). با `print(data)` دو مقدارِ دیگر — `winddirection` و `is_day` — را پیدا کن و به OLED اضافه کن. در دفترچهٔ مهندسی، ساختارِ تودرتوی پاسخ را مثلِ یک درخت بکش: کدام کلید در کدام لایه بود؟
- **تمرین ستاره‌دار ⭐:** یک «شناسنامهٔ JSON» برای رباتِ ترم ۳ خودت بساز: دیکشنریِ تودرتویی با اسم، سرعتِ کالیبره، لیستِ سنسورها و یک دیکشنریِ تنظیمات (`BURST` و بقیه از فصل قبل). با `json.dumps` متنش کن و در دفترچه‌ات ثبت کن؛ بعد همان متن را در Shell با `loads` برگردان و ثابت کن سفرِ دوطرفه بدونِ گم‌شدنِ داده کار می‌کند!

## در فصل بعد

همه‌چیز آماده است: زبانِ JSON را بلدی، خانهٔ امنِ کلید را ساخته‌ای، می‌دانی API key چیست. جلسهٔ بعد روزِ برداشت است: والدینت یک کلیدِ رایگانِ Gemini می‌سازند و تو برای اولین بار از کدِ خودت به یک هوش مصنوعی پیام می‌فرستی و جوابش را — بله، به شکلِ JSON! — می‌گیری. اولین «سلام» بینِ کدِ تو و AI. باور کن، لحظه‌ای است که یادت نمی‌رود!

</div>

---
Source: https://yaadestan.com/courses/airo/lessons/t4/s06-json-apikeys (یادستان, Yaadestan)
