Wejście: API
API narzędzia do sprawdzania DR: każdy parametr i pole wyjaśnione
Odnośnik do kształtu żądania i dwóch pól, które zawiera każda uwierzytelniona odpowiedź. Wiersze specyficzne dla akcji różnią się, dlatego przed parsowaniem warto wykonać jedno testowe wywołanie.
Usługa to REST API zwracające JSON. CORS jest otwarty. Strona przeglądarki może wywoływać go bezpośrednio. Klucze zaczynają się od sk_ i pochodzą ze strony konta po zalogowaniu przez Google.
Adres bazowy to https://rankupedia.com/api.php. Uwierzytelnij się za pomocą key=sk_... w ciągu zapytania lub za pomocą nagłówka Authorization: Bearer sk_..., zgodnie z preferencjami Twojego klienta. Cztery akcje nie wymagają uwierzytelnienia: domain, overview, stats i suggest.
Narzędzie do sprawdzania DR jest przydatne dopiero wtedy, gdy potrafisz zinterpretować jego wyniki. Poniższy przykład to najmniejszy użyteczny przypadek, a sekcje po nim omawiają elementy, w których ludzie najczęściej popełniają błędy.
Jedno wywołanie, z adnotacjami
Darmowa akcja overview. Zastąp domenę swoją własną.
curl "https://rankupedia.com/api.php?action=overview&q=nytimes.com"
# authenticated listing, 100 rows per page:
curl -H "Authorization: Bearer sk_live_..." \
"https://rankupedia.com/api.php?action=refdomains&q=nytimes.com&per=100&page=1&order=desc"Anatomia żądania
Wybierz akcję
Wartość action wybiera operację i cenę. Darmowe akcje są wymienione w tabeli kosztów.
Nazwij cel
Wartość q to sama domena, np. nytimes.com, bez schematu ani ścieżki.
Dodaj poświadczenia, jeśli akcja jest płatna
Lub key w ciągu zapytania, lub nagłówek Bearer. Nagłówki utrzymują klucze z dala od dzienników serwera i historii przeglądarki.
Stronicowanie i sortowanie
page i per dzielą wyniki, a sort z order je porządkują. Stronicowanie kończy się na 50 000 wierszach.
Przygotowanie listy domen przed pierwszym wywołaniem
Wiele dziwnych wyników zaczyna się od danych wejściowych, a nie od serwera. Wyczyść listę raz, a następnie ją wyślij.
Usuń wszystko, co nie jest samą domeną. Wklejony adres ze ścieżką dodaje znaki, których nie oczekuje wartość q, więc usuń schemat, ścieżkę i ewentualny ukośnik na końcu.
Usuń schemat i ścieżkę
Zmień https://shop.example.org/blog/ na shop.example.org przed wywołaniem. Wartość q przyjmuje samą domenę, więc ścieżka jest odrzucana w tym miejscu, a nie wysyłana.
Arkusze kalkulacyjne ukrywają te szczegóły wewnątrz komórek. Szybkie filtrowanie ukośników i dwukropków wychwyci większość z nich.
Zamień nazwy na małe litery i usuń duplikaty
Nazwy domen nie są wrażliwe na wielkość liter, więc Example.COM i example.com oznaczają ten sam cel. Wysłanie obu zużywa kredyty dwukrotnie dla jednej odpowiedzi.
Usuń duplikaty przed policzeniem wywołań. Lista 2100 nazw z 300 duplikatami wymaga dwóch wywołań bulk_dr w wersji surowej, ale po usunięciu duplikatów jej 1800 unikalnych nazm mieści się w jednym wywołaniu.
Decyzja między domeną główną a poddomeną
Poddomena, taka jak blog.example.org, jest osobną nazwą na Twojej liście. Zdecyduj, o którą z nich pytasz, zanim wyślesz cokolwiek.
Jeśli pytanie dotyczy całej witryny, wyślij nazwę główną. Jeśli dotyczy jednej poddomeny, przetestuj dokładnie tę nazwę i traktuj odpowiedź jako odnoszącą się tylko do niej.
Zapisz decyzję w notatkach zadania, aby kolejne uruchomienie, być może przez inną osobę, stosowało tę samą regułę.
Parametry zapytania
| Parametr | Znaczenie | Uwagi |
|---|---|---|
| action | Którą operację uruchomić | Wymagane; zobacz tabelę kosztów |
| q | Docelowa domena | Przykład: nytimes.com |
| key | Klucz API | Lub użyj nagłówka Bearer |
| page | Numer strony wyników | Głębokie stronicowanie jest ograniczone do 50 000 |
| per | Wiersze na stronę | Przyjmuje wartości od 10 do 5000; jedno wywołanie to jeden ładunek, przy dowolnej liczbie wierszy |
| sort | Kolumna do sortowania | Dostępne kolumny zależą od akcji |
| order | asc lub desc | Używaj razem z sort |
| domains | Lista dla bulk_dr | Maks. 2000 domen za razem, przez GET lub ciało POST |
Przechodzenie przez długą listę
Akcje listujące zwracają wiersze w postaci stron. Dwa parametry kontrolują podział: page wybiera, który kawałek, a per ustala, ile wierszy zawiera. Per przyjmuje wartości od 10 do 5000.
Najpierw wybierz rozmiar strony. Większe per zmniejsza liczbę wywołań, a rozliczenie liczy wywołania, a nie wiersze.
Sortuj przed stronicowaniem
Sort i order decydują, które wiersze trafią na pierwszą stronę. Ustaw oba przy każdym wywołaniu w serii, aby każda strona pochodziła z tego samego porządku.
Użyj desc na kolumnie metryki, gdy chcesz mieć najsilniejsze wiersze na początku, i asc, gdy szukasz najsłabszych. Dostępne nazwy kolumn zależą od akcji.
Potwierdź kolejność małym testem dwóch stron, zanim zaufasz długiemu uruchomieniu.
Zatrzymaj się na limicie 50 000 wierszy
Głębokie stronicowanie zatrzymuje się na 50 000 wierszach. Po tym punkcie wywołanie nie zwraca nic nowego, więc pętla, która ciągle stronicuje, marnuje kredyty.
Zwęż pytanie lub podziel zadanie na mniejsze uruchomienia. Drugie zapytanie z innym celem jest zwykle czystsze niż głębsza strona.
Limit głębokości jest właściwością listowania, więc dotyczy każdego klienta, który go wywołuje.
Zakończ pętlę na krótkiej stronie
Zatrzymaj się, gdy strona zwróci mniej wierszy niż per. To zwykły znak, że lista się skończyła.
Połącz ten test z sprawdzeniem salda w wpisie rozwiązywania problemów, aby pętla kończyła się na ostatniej stronie lub przy niskim saldzie, whichever comes first.
Pola obecne w każdej odpowiedzi
ok
Typ logiczny. Prawda oznacza, że wywołanie się zakończyło. Fałsz oznacza, że nie, a status HTTP mówi dlaczego.
_credits
Pojawia się przy wywołaniach uwierzytelnionych. Raportuje koszt tego wywołania i Twoje pozostałe saldo kredytów, co pozwala zatrzymać pętlę przed wyczerpaniem salda.
Nazwy pól na poziomie wiersza dla każdej akcji są widoczne w żywej odpowiedzi. Nie powielamy ich w tym wpisie, aby nie odbiegały od usługi.
Testowanie wywołania przed napisaniem pętli
Wybierz znaną domenę
Wybierz witrynę, której profil możesz ocenić na podstawie jej własnych stron. Domena, którą znasz, ułatwia zauważenie dziwnych liczb.
Wyślij jedno darmowe wywołanie
Uruchom overview lub domain bez klucza. Odpowiedź pokazuje rzeczywisty kształt JSON, który jest bardziej niezawodny niż jakikolwiek opis, w tym ten.
Wyślij jedno płatne wywołanie z najmniejszą stroną
Użyj per=10 w akcji listującej. Zobaczysz pola wierszy i wartość _credits przed skalowaniem.
Przeczytaj _credits, a następnie skaluj
Pomnóż koszt jednego wywołania przez liczbę wywołań w Twoim planie. Jeśli suma jest większa niż saldo, zmniejsz plan przed rozpoczęciem pętli.
Przed wdrożeniem klienta
- Sprawdź ok przed odczytaniem jakiejkolwiek innej wartości
- Loguj _credits przy każdym wywołaniu
- Traktuj dane jako miesięczny snapshot
- Obsługuj 401 i 402 osobno, zobacz wpis rozwiązywania problemów
- Utrzymuj klucz z dala od kodu front-end
Uwagi dotyczące batchowania
Akcja bulk_dr przyjmuje do 2000 domen na wywołanie. Wyślij je jako wartość zapytania domains lub jako ciało POST, gdy lista jest zbyt długa na URL.
compare przyjmuje do 20 domen, a intersect przyjmuje 2 do 10. Intersect odpowiada na jedno pytanie: które witryny linkują do wszystkich wymienionych domen.
Ponieważ rozliczenie jest za wywołanie, większe batchy są zawsze tańsze na wiersz. Zawodzą też jako jedna jednostka. Podziel na rozmiary, które można ponowić.
Długie listy mogą trafić do ciała POST. Przeczytaj ok przed czymkolwiek innym w odpowiedzi, ponieważ odrzucony batch nie zawiera wierszy, których można użyć.
Czytanie JSON bez założeń
Parsery psują się na polach, które odpowiedź pomija. Kod, który oczekuje każdej klucza w każdym wierszu, jest kruchy, a jeden krótki wiersz może zatrzymać całe zadanie.
Traktuj brakujące pola jako normalne
Pola wiersza zależą od akcji, więc pole obecne w jednym listowaniu może być nieobecne w innym. Nadaj każdej polu wartość domyślną i kontynuuj.
Loguj, które pole było brakujące, a nie tylko to, że coś się nie powiodło. Ten log pokazuje, czy zmienił się schemat, czy Twój własny kod.
Przechowuj surowe odpowiedzi dla próbki
Zapisz surowy JSON pierwszych kilku wywołań w każdym nowym zadaniu. Gdy liczba później wygląda źle, zapisany tekst rozstrzyga pytanie szybciej niż pamięć.
Przechowuj próbkę z datą i nazwą akcji. Miesięczne odświeżanie oznacza, że to samo wywołanie może zwracać inne wiersze w przyszłym miesiącu.
Akcje według rodziny
| Rodzina | Akcje | Typowe użycie |
|---|---|---|
| Darmowe | domain, overview, stats, suggest | Szybkie wyszukiwania i autouzupełnianie |
| Ocenianie | bulk_dr, compare, dr_distribution | Filtrowanie list i zbiorów porównawczych |
| Listowanie | refdomains, backlinks, anchors, toppages, anchor_cloud | Audyt jednej witryny |
| Wyszukiwanie | search, keyword, intersect | Znajdowanie, kto linkuje z danym anchor text lub do kilku rywali |
Nazwy pól na poziomie wiersza różnią się w zależności od akcji i nie są tutaj wymienione. Wywołaj endpoint z darmową akcją na znanej domenie i przeczytaj JSON, który jest jedynym autorytatywnym źródłem.
Pytania o parametry, które zadają programiści
Cztery pytania o parametry obejmują większość pierwszego tygodnia z API.
Czy potrzebuję klucza do każdego wywołania?
Nie. Akcje domain, overview, stats i suggest nie wymagają klucza. Płatne akcje go wymagają, wysyłanego albo jako parametr key, albo jako nagłówek Bearer.
Czy mogę wysłać klucz w URL?
Tak, parametr key działa w ciągu zapytania. Nagłówek utrzymuje klucz z dala od samego adresu, co wiele zespołów preferuje dla dzienników i udostępnionych linków.
Co jeśli chcę per powyżej 5000?
Dokumentowany zakres to 10 do 5000. Wartości spoza niego wypadają poza to, co opisuje ten wpis, więc trzymaj wartość w zakresie i stronicuj więcej.
Czy wielkość liter ma znaczenie w q?
Nazwy domen nie są wrażliwe na wielkość liter, więc zamień wartość na małe litery przed wysłaniem. Jedna pisownia ułatwia porównywanie wyników między uruchomieniami.
