Python ile Orijinal Operatör Sorgulama API'si: requests ile Tekli ve Çoklu İstekler

requests kütüphanesi ile tekli ve çoklu operatör sorgulamaları, hata yönetimi ve sıralı sonuçların satırlarla eşleştirilmesi üzerine bir Python rehberi.

Python'da bir operatör sorgulama API'sini çağırmak için, tek bir sonuç almak üzere E.164 formatındaki bir numarayı /api/v1/check adresine veya sıralı bir sonuç kümesi için 100 numaraya kadar olan bir listeyi /api/v1/batch-check adresine POST isteği ile gönderin. API anahtarını güvenilir bir sunucudan X-API-Key başlığı ile gönderin, bir zaman aşımı süresi belirleyin, verileri okumadan önce yanıt kodunu kontrol edin ve çoklu sonuçları konumlarına ve tanımlayıcılarına göre satırlarınızla eşleştirin. Döndürülen operatör, mevcut ağ değil, orijinal tahsisat bilgisidir.

Operatör sorgulamaları için bir requests oturumu oluşturun

requests kütüphanesi, HTTP çağrılarını kısa tutar ve bir oturum nesnesi, her çağrının başlıkları ve bağlantıyı paylaşmasına olanak tanır. pip install requests ile kütüphaneyi yükleyin ve anahtarı bir ortam değişkeninden okuyarak kaynak kodun dışında tutun.

import os
import requests

BASE_URL = "https://carrierlookup.online"

session = requests.Session()
session.headers.update({
    "X-API-Key": os.environ["CARRIERLOOKUP_API_KEY"],
    "Accept": "application/json",
})

Başlangıçtan itibaren şu üç alışkanlığı edinmek faydalıdır:

• Bu kodu yalnızca güvenilir bir sunucuda, bir işçide veya kontrolünüz altındaki bir not defterinde çalıştırın. Anahtarı asla bir tarayıcıda veya mobil uygulamada dağıtmayın.
• Her çağrıya mutlaka bir timeout değeri geçin. Aksi takdirde, requests süresiz olarak bekleyebilir.
• Numaraları göndermeden önce E.164 formatına normalleştirin: başında artı işareti, ülke kodu ve abone numarası olacak şekilde, boşluk veya ayırıcı karakter içermemelidir.

Ayırıcıları temizleyen ve artı işaretini ekleyen küçük bir yardımcı fonksiyon, tekrarlanan temizlik işlemlerinden tasarruf sağlar ve sonuçlarınızdaki biçimlendirme sorunlarını önler. Reddedilen bir format, operatör yanıtı değil, bir biçimlendirme sorunudur; bu nedenle isteği göndermeden önce bu durumu ele alın.

/api/v1/check adresine tekli sorgu gönderin

Gerçek zamanlı tekli sorgu POST /api/v1/check adresidir. Tek bir E.164 numarası alır ve aynı yanıt içerisinde cevap verir. Numarayı, API dokümantasyonunda açıklandığı gibi JSON gövdesinde gönderin.

def check_one(number: str) -> dict | None:
    resp = session.post(
        f"{BASE_URL}/api/v1/check",
        json=build_single_payload(number),  # gövde yapısı: API dokümanlarına bakın
        timeout=65,
    )
    resp.raise_for_status()
    body = resp.json()
    if body.get("code") != 0:
        print("tamamlanamadı:", body.get("msg"))
        return None
    return body["data"]

Gövde bir code, bir msg ve düz bir data nesnesine sahiptir. Sıfır olan bir code, sorgulamanın tamamlandığı anlamına gelir. Veri; orijinal operatörü, alt operatörü, numara türünü, ülke kodunu, bölgeyi ve şehri içerir. İsteğe bağlı değerlerden herhangi biri boş olabilir ve tüm operatör değerleri boş olan tamamlanmış bir sonuç yine de normal bir sonuçtur. Boş değerleri, numaranın operatörü olmadığına dair bir kanıt olarak değil, mevcut değil şeklinde saklayın.

Sıfır olmayan bir code, sorgulamanın tamamlanmadığı anlamına gelir; örneğin bir cevap belirlenemediğinde. Bu durumu boş bir başarıya dönüştürmeyin. Başarısız veya Belirlenemedi sonuçları için ücret alınmaz, bu nedenle kısa bir gecikme ile yeniden denemek makuldür. Genel dokümantasyon, gerçek zamanlı çağrılar için zaman aşımı sınırlarını listeler, bu nedenle istemci zaman aşımınızı tekli istekler için belgelenen sınırda veya üzerinde tutun.

Çoklu istek gönderin ve sonuçları satırlarla eşleştirin

Küçük bir grubunuz olduğunda, POST /api/v1/batch-check 1 ile 100 arasında E.164 numarası alır ve sıralı, eşzamanlı bir sonuç döndürür. Numaralar farklı ülkelerden olabilir. Yanıt, kaç öğe olduğunu, kaçının başarılı olduğunu ve kaçının başarısız olduğunu özetler ve ardından her girdi için sırayla bir sonuç listeler.

def check_many(numbers: list[str]) -> list[dict]:
    resp = session.post(
        f"{BASE_URL}/api/v1/batch-check",
        json=build_multi_payload(numbers),  # gövde yapısı: API dokümanlarına bakın
        timeout=310,
    )
    resp.raise_for_status()
    body = resp.json()
    if body.get("code") != 0:
        raise RuntimeError(body.get("msg"))
    return body["data"]["results"]

Sonuçları satırlarınıza eklemek için, girdi listesini sonuç listesiyle eşleştirin (zip) ve her öğenin tanımlayıcısının gönderdiğiniz numarayla eşleştiğini kontrol edin. Bu ikinci kontrol, istek oluşturma ve gönderme arasında bir liste değiştirilirse oluşabilecek sessiz uyumsuzluklara karşı sizi korur.

Her öğe ayrıca bir exists bayrağı taşır. Bu bayrak false olduğunda, öğenin normal bir sonucu yoktur. Bu, geçersiz veya bağlantısı kesilmiş bir numara ile aynı şey değildir, bu nedenle bunu sonuç yok olarak saklayın ve daha sonra yeniden denemeye veya bırakmaya karar verin. Zaman aşımına uğrayan bir çoklu istek bir bütün olarak başarısız olur ve kısmi sonuç döndürmez; tam tutar iade edilir, bu nedenle güvenli yanıt aynı parçayı yeniden denemektir.

Hesap başına aynı anda yalnızca bir çoklu istek çalışır, bu nedenle parçaları işleyen bir döngü, bir sonrakini göndermeden önce her çağrının bitmesini beklemelidir.

Parçalara ayırın, yeniden deneyin ve bakiyeyi kontrol edin

Gerçek listeler 100 numaradan uzundur, bu nedenle onları parçalara ayırın ve her birini sırayla işleyin.

def chunks(items, size=100):
    for i in range(0, len(items), size):
        yield items[i:i + size]

rows = []
for part in chunks(clean_numbers):
    rows.extend(check_many(part))

Birkaç pratik kural bu döngüyü güvenilir kılar:

1. Önce temiz listeyi tekilleştirin, böylece her numara bir kez sorgulanır.
2. requests.exceptions.Timeout ve ConnectionError hatalarını API hatalarından ayrı olarak yakalayın ve sınırlı sayıda duraklama ile yeniden deneyin.
3. Eşzamanlılığı düşük tutun. Genel dokümantasyon, paylaşılan az sayıda gerçek zamanlı işlem yuvasını tanımlar ve dakika başına sabit bir sınır yayınlamaz, bu nedenle birçok paralel iş parçacığı çalıştırmaktan kaçının.
4. Tamamlanan her parçayı döner dönmez diske veya bir veritabanına yazın, böylece bir çökme durumunda tamamlanmış işler kaybolmaz.

Büyük bir işlemden önce GET /api/v1/balance çağrısı yapın. Bu, hiçbir ücret almadan hesap bakiyesini okur ve komut dosyasının yarı yolda başarısız olmak yerine net bir mesajla erken durmasını sağlar. Hem gerçek zamanlı hem de dosya hizmetleri tek bir bakiyeyi paylaşır ve tamamlanan numara başına ücretlendirilir.

Birkaç parçadan çok daha büyük listeler için, eşzamanlı çağrılardan oluşan uzun bir döngü yerine eşzamansız bir dosya görevi daha uygundur. Bir dosya görevi, çoklu isteğin daha büyük bir versiyonu değil, kendi uç noktasına sahip ayrı bir iş akışıdır.

Sonuçları sorumlu bir şekilde yorumlayın

Veriler bir pandas çerçevesinde veya veritabanında olduğunda, temel risk veriyi aşırı yorumlamaktır. Operatör, numara aralığının orijinal olarak tahsis edildiği operatördür. Numara taşıma işleminden sonra, kişi başka bir operatör kullanıyor olabilir. Bölge ve şehir, tahsisat coğrafyasını tanımlar, kişinin veya telefonun şu an nerede olduğunu değil. Numara türü size aralığın türünü söyler, hattın aktif olup olmadığını değil.

İyi kullanım alanları arasında; sağlayıcı yönlendirme testleri için kayıtları gruplandırma, inceleme için olağandışı numara türlerini işaretleme ve bir CRM'e bağlam sütunları ekleme yer alır. Kötü kullanım alanları arasında; bir numaraya ulaşılabileceğine veya ulaşılamayacağına karar verme, kime ait olduğunu varsayma veya onay çıkarımı yapma yer alır.

Basit bir şema anlamı net tutar: orijinal operatör, alt operatör, numara türü, ülke kodu, bölge, şehir, sorgulama durumu ve sorgulama zamanı. Durum sütunu; tamamlanmış, boş ve başarısız sonuçları ayırır, böylece sonraki raporlar bunları birbirine karıştırmaz.

SSS

Operatör sorgulama API çağrıları için hangi Python kütüphanesi en iyisidir?

requests kütüphanesi hem tekli hem de çoklu uç noktalar için yeterlidir. API anahtarı başlığını paylaşmak için bir oturum kullanın, her zaman bir zaman aşımı süresi belirleyin ve raise_for_status ile yanıt kodunu kontrol edin. Çok sayıda eşzamanlı iş için havuzu küçük tutun çünkü gerçek zamanlı yuvalar hesap genelinde paylaşılır.

Ekipler çoklu sonuçları girdi satırlarıyla nasıl eşleştirebilir?

Sonuçlar girdi sırasıyla geri döner ve her öğe gönderilen tanımlayıcıyı tekrarlar. Girdi listesini sonuçlarla eşleştirin (zip), ardından verileri yazmadan önce her tanımlayıcının satırıyla eşleştiğini doğrulayın. exists bayrağının false olduğu öğeler, geçersiz numaralar olarak değil, normal bir sonucu olmayan öğeler olarak saklanmalıdır.

API anahtarı bir Python projesinde nerede bulunmalıdır?

Anahtarı bir ortam değişkeninde veya güvenilir bir sunucudaki bir gizli yönetim sisteminde tutun ve başlangıçta okuyun. Kaynak kontrolüne işlemeyin veya tarayıcı ya da mobil koddan göndermeyin. Bir günlüğe veya depoya sızarsa, anahtarı yenileyin ve son kullanımı gözden geçirin.

Daha Fazla Bilgi

İş akışınızdaki bir sonraki adıma uygun ürün bilgilerini seçin.

• Ürün dokümantasyonunu görüntüleyin →
• Ekiple görüşün →