Гузариш ба мундариҷа
Мавзӯи 3 аз 6

Параметрҳо ва сарлавҳаҳо

Чаро параметрҳо ва сарлавҳаҳо лозиманд

Як суроғаи API метавонад ҳазорҳо дархости гуногунро қабул кунад: ҷустуҷӯ бо калимаҳо, интихоби гурӯҳ, мураттабсозӣ ва гирифтани саҳифаи рӯйхат. Параметрҳо муайян мекунанд, ки кадом маълумот лозим аст; сарлавҳаҳо мегӯянд, ки чӣ гуна муошират кунем. Агар вазифаи онҳоро омехта кунем, сервер дархости дигар мегирад, ҳатто агар суроға дуруст намояд.

Дар ин лексия дархостҳои омодашударо истифода мебарем: requests.Request(...).prepare() он чизеро месозад, ки ба шабака фиристода мешуд, вале чизе намефиристад. Ин роҳи қулайи санҷидани рамзгузорӣ ва сарлавҳаҳо бе интернет аст. Блокҳоро бо тартиб дар як раванди Python иҷро кунед; example.test танҳо суроғаи омӯзишӣ аст.

Параметрҳо: рамзгузориро ба китобхона супоред

Пас аз ? дар URL сатри параметрҳо, ё query string, меояд. Ҷуфтҳо одатан бо &, ном ва қимат бо = ҷудо мешаванд. Дар дохили қимат ин аломатҳо бояд рамзгузорӣ шаванд, вагарна сервер онҳоро ҷудокунанда мешуморад. params луғатро гирифта, ин корро худкор мекунад.

import requests
from urllib.parse import parse_qs, urlsplit, urljoin

req = requests.Request("GET", "https://example.test/search",
                       params={"q": "C++ & Python", "page": 3}).prepare()
print(req.url)
print(parse_qs(urlsplit(req.url).query))

Барориш:

https://example.test/search?q=C%2B%2B+%26+Python&page=3
{'q': ['C++ & Python'], 'page': ['3']}

C++ маҳз C++ монд: плюсҳои аслӣ ба %2B табдил ёфтанд. Фосила бо плюс, амперсанд бо %26 рамзгузорӣ шуд. parse_qs аз китобхонаи стандартӣ табдили баръаксро дар тарафи қабулкунанда нишон медиҳад. Қиматҳои он рӯйхатанд, зеро як калид метавонад чанд бор ояд.

Пеш аз додан ба params фосилаҳоро дастӣ иваз накунед: китобхона +-и гузоштаро плюси аслӣ фаҳмида, боз рамзгузорӣ мекунад. Матни аслиро бо фосилаҳо, фоизҳо ва ҳарфҳои миллӣ диҳед.

Як параметр бо чанд қимат

Баъзе API-ҳо чанд нишона (tag)-ро бо як ном қабул мекунанд. Рӯйхат дар params ба калиди такроршаванда табдил меёбад. API-и дигар метавонад ба ҷойи ин сатри бо вергул ҷудошударо талаб кунад: форматро ҳуҷҷатҳои он муайян мекунанд.

req = requests.Request("GET", "https://example.test/items",
                       params={"tag": ["http", "python"]}).prepare()
print(req.url)

Барориш:

https://example.test/items?tag=http&tag=python

Барои санҷидани ҷавоби воқеӣ r.request.url-ро бинед: ин URL-и дархости фиристодашуда аст. r.url суроғаи ҷавобро нишон медиҳад ва баъди равонасозӣ метавонад фарқ кунад. Суроғаҳои дорои параметрҳои махфиро дар log нашр накунед.

Сарлавҳаҳо: формат, барнома ва дастрасӣ

Сарлавҳа сатри хизматии номдор дар HTTP аст. Луғати headers сатрҳо дорад, на маълумоти дилхоҳи дарунсохт. Accept формати дилхоҳи ҷавобро тавсиф мекунад. User-Agent номи барномаро мегӯяд. Authorization маълумоти дастрасиро медиҳад; нақшаи Bearer калимаи Bearer, фосила ва token-ро талаб мекунад.

headers = {"Authorization": "Bearer demo", "Accept": "application/json",
           "User-Agent": "study-client/1.0"}
req = requests.Request("GET", "https://example.test/profile",
                       headers=headers).prepare()
print(req.headers["authorization"])
print(req.headers["Accept"])
print(req.headers["user-agent"])

Барориш:

Bearer demo
application/json
study-client/1.0

Номи сарлавҳа ба калон ё хурд будани ҳарфҳо вобаста нест, вале қиматаш метавонад вобаста бошад. Token-ҳои demo ва DEMO метавонанд ҳуқуқҳои гуногун диҳанд. Бе талаби равшани протокол token-ро бо strip() «ислоҳ» накунед. Қимати омӯзишии demo ба API-и воқеӣ дастрасӣ намедиҳад.

Маълумоти махфиро одатан аз тағйирёбандаи муҳит, масалан os.environ["API_TOKEN"], пас аз танзими муҳит мехонанд. Тағйирёбандаи набуда KeyError медиҳад, бинобар ин мавҷудияташро дар оғоз месанҷанд. HTTPS интиқолро муҳофизат мекунад, аммо сирри дар коди умумӣ ё log навишташударо наҷот намедиҳад. Accept ва Content-Type низ фарқ доранд: якум дар бораи ҷавоби дилхоҳ, дуюм дар бораи формати бадани фиристодашаванда аст.

Пайванди пурра ва нисбӣ

API метавонад URL-и пурра, роҳ аз реша ё пайванди нисбӣ диҳад. Реша қисми баъди номи сервер аст, ки бо / оғоз мешавад. Роҳи нисбӣ аз «ҷузвдони» ҷорӣ ҳисоб мешавад. urljoin қоидаҳои браузерро татбиқ мекунад; ҷамъкунии сатрҳо ин қоидаҳоро намедонад.

page = "https://example.test/v1/catalog?cursor=a"
print(urljoin(page, "https://cdn.example.test/image.png"))
print(urljoin(page, "/help"))
print(urljoin(page, "catalog?cursor=b"))
print(urljoin("https://example.test/v1/catalog/", "next"))

Барориш:

https://cdn.example.test/image.png
https://example.test/help
https://example.test/v1/catalog?cursor=b
https://example.test/v1/catalog/next

Мисоли охир аҳамияти /-и охирро нишон медиҳад: catalog/ ҷузвдон ҳисоб мешавад, вале catalog ҷузъи охири роҳ аст, ки пайванди нисбӣ онро иваз мекунад. Пайванди бо ? оғозшуда параметрҳои роҳи ҷориро иваз мекунад. urljoin дархост намефиристад ва дастрасии суроғаро намесанҷад.

URL-и пурра метавонад ба сервери дигар ишора кунад. Дар муштарии воқеӣ пеш аз фиристодани сарлавҳаҳои махфӣ ба пайванд аз манбаи нобовар суроғаҳои иҷозатдодашударо санҷед. Дуруст сохтани суроға ва қарор дар бораи бовар ба он қадамҳои ҷудоанд.

Додани маълумот саҳифа ба саҳифа

Маҷмӯаҳои калонро ба саҳифаҳо ҷудо мекунанд. Дар як API муштарӣ page-ро зиёд мекунад, дар дигар сервер next — пайванд ё cursor-и идомаро медиҳад. Cursor нишонаи мавқеъ аст: онро бе кӯшиши фаҳмидани муҳтавояш боз мефиристанд. Шарти анҷомро API муайян мекунад.

pages = [{"items": ["A"], "next": "?cursor=b"},
         {"items": [], "next": "?cursor=c"},
         {"items": ["B"], "next": None}]
for data in pages:
    print(len(data["items"]), data["next"] is not None)

Барориш:

1 True
0 True
1 False

Саҳифаи миёна холӣ аст, вале идома дорад. Агар қоидаи API аз next истифода барад, набудани унсурҳо худ аз худ анҷом нест. Ҳамзамон бо гузаштан ба пайванди тайёр рақами саҳифаро зиёд накунед: шояд cursor-и зарурӣ аллакай дар он бошад. Барои сохтани суроғаи пурраи дархости нав суроғаи ҷавоби ҷориро, махсусан баъди равонасозӣ, ба назар гиред.

Сохтани дархост аз қисмҳои мустақил

Мисоли нав филтр, рақами саҳифа ва формати ҷавобро якҷо мекунад. Маълумоти филтр дар params, маълумоти хизматӣ дар headers мемонад. Ин қадами хурди омодагӣ ба масъалаҳои ҷустуҷӯ ва гузаштан аз API аст, на гузариши тайёри ҳамаи саҳифаҳо.

req = requests.Request("GET", "https://example.test/catalog",
                       params={"category": "books & maps", "page": 2},
                       headers={"Accept": "application/json"}).prepare()
print(req.method)
print(req.url)
print(req.headers["Accept"])

Барориш:

GET
https://example.test/catalog?category=books+%26+maps&page=2
application/json

Дар дохил чӣ рӯй медиҳад

Аввал requests суроғаи асосӣ ва параметрҳои рамзгузоришударо якҷо мекунад, сипас сарлавҳаҳоро месозад. Сервер query string-ро таҳлил карда, манбаъро интихоб ва формат ва дастрасиро месанҷад. Дар ҷавоб маълумот ва шояд пайванди идомаро медиҳад. Муштарӣ алоҳида қарор мекунад, ки дархости нав лозим аст ё не. Феҳристи китобхонаро тасаввур кунед: параметрҳо шартҳои ҷустуҷӯ, сарлавҳаҳо билети хонанда ва забони хизматрасонӣ, next ишора ба гурӯҳи навбатии кортҳо аст.

Хатоҳои маъмул ва ислоҳи онҳо

  1. base + "?q=" + query. & қиматро мебурад, # бошад фрагментеро оғоз мекунад, ки ба сервер намеравад. params={"q": query} диҳед.
  2. params={"q": query.replace(" ", "+")}. Сервер ба ҷойи фосила плюсҳои аслӣ мегирад. Сатри аслиро нигоҳ доред.
  3. headers={"Authorization": token} барои Bearer API. Нақша намерасад ва одатан 401 мегиред. Нақшаро дар формати талабкардаи API илова кунед.
  4. current + next_link. Роҳи нодуруст ё ду суроғаи часпида ҳосил мешавад. urljoin-ро истифода баред ва маънои /-и охирро санҷед.
  5. Қатъ дар if not data["items"]. Саҳифаҳои баъди саҳифаи холии миёна гум мешаванд. Ба аломати анҷоми ваъдакардаи API, масалан набудани next, такя кунед.

Ёддошт

Чӣ мефиристем Чӣ гуна
Қимати ҷустуҷӯ params={"q": query}
Чанд нишона params={"tag": ["a", "b"]}
Сатрҳои хизматӣ headers={"Accept": "application/json"}
Дастрасӣ бо Bearer Authorization: Bearer ...
Пайванд нисбат ба саҳифаи ҷорӣ urljoin(current, link)
Идомаи рӯйхат Аз рӯйи қоидаи page, next ё cursor-и ҳамин API