Asana — jak używać: integracje i limity

Asana API pozwala aplikacjom wymieniać dane z Asaną.
W tym poradniku znajdziesz operacje na zadaniach, zasady budowania żądań i odczytywania odpowiedzi, limity zapytań oraz webhooki – powiadomienia o zmianach danych.

Czym jest Asana API i jak pomaga zarządzać zadaniami?

Przez API można programowo tworzyć zadania, odczytywać je i zmieniać ich dane.
W procesie opisanym przez użytkownika Zapier przekazywał do Asana API fragmenty podsumowania projektu wygenerowanego przez AI, aby ustawić status projektu¹. Udane utworzenie aktualizacji statusu przez POST /status_updates zwraca kod HTTP 201².

Jakie operacje na zadaniach umożliwia Asana API?

Asana API pozwala tworzyć zadania, pobierać ich dane i aktualizować pola. Zadanie i projekt to osobne zasoby, dlatego przed wysłaniem żądania trzeba wybrać właściwy punkt końcowy. Użytkownik planujący migrację z ClickUp do Asany opisał skrypt przenoszący dane i zapytał o dodawanie wiadomości do projektu przez API³.
Wiadomość projektu dotyczy komunikacji w projekcie, a komentarz do zadania – konkretnego zadania. Nie są to te same wpisy. Sposób odczytu obu zasobów pokazuje tabela:

Każde z tych żądań pobiera dane jednego wskazanego zasobu: zadania albo projektu⁴.

Jak wysłać żądanie do Asana API i odczytać odpowiedź?

Żądanie trafia do punktu końcowego przypisanego do wybranego zasobu. Dokumentacja API w wersji beta zawierała przykładowe żądania i odpowiedzi dla każdego punktu końcowego. Automatycznie kontrolowała też poprawność informacji⁵.

• Uwierzytelnienie przekazuje w żądaniu uprawnienia aplikacji do działania w Asanie.
• Metoda i punkt końcowy wskazują operację oraz zasób, którego dotyczy.
• Odpowiedź zawiera wynik żądania, a kod HTTP informuje o powodzeniu lub błędzie.

Tekst sformatowany musi odpowiadać formatowi obsługiwanemu przez Asanę. Jej API wspiera tylko niewielką część HTML¹.
Pole html_notes wymaga poprawnie sformatowanego fragmentu XML z jednym głównym elementem <body>⁶.

Jak tworzyć, odczytywać i aktualizować zadania przez Asana API?

Metodę żądania dobiera się do operacji na zadaniu: POST tworzy zadanie, GET je odczytuje, a PUT aktualizuje⁷.

Tabela zestawia metody, punkty końcowe i cele operacji na zadaniach⁷.

Jak rozpoznać i naprawić typowe błędy Asana API?

Kod HTTP sygnalizuje nieudane żądanie, więc przed ponowieniem operacji trzeba go odczytać. Jeden z użytkowników zgłosił odpowiedź HTTP 400 podczas dodawania zadań przez serwer⁸.
Poszczególne błędy wymagają innych działań:

Takie znaczenie kodów podaje dokumentacja API⁹.

• Treść żądania warto porównać ze schematem operacji tworzenia zadania.
• Identyfikatory i pola trzeba sprawdzić pod kątem wartości oraz wymaganego formatu¹⁰.
• Odpowiedź serwera pomaga powiązać komunikat błędu z wysłanym żądaniem.

Właściwy dobór metody, zasobu i danych pozwala automatyzować pracę z zadaniami.
Gdy żądanie POST /tasks utworzy zadanie, serwer potwierdza to odpowiedzią HTTP 201¹¹.

Czym są zasoby i limity Asana API?

Asana API udostępnia zasoby, między innymi projekty i zadania. Punkt końcowy określa zasób, na którym aplikacja działa, a limit zapytań wyznacza tempo komunikacji.
Aplikacja powinna rozróżniać błędne żądanie od przekroczenia limitu, bo każdy przypadek wymaga innej reakcji⁹.

Jakie limity zapytań obowiązują w Asana API?

Standardowy limit zależy od rodzaju domeny i obowiązuje osobno dla tokenu autoryzacyjnego¹².
Tabela przedstawia dopuszczalną liczbę żądań na minutę:

Po przekroczeniu limitu API zwraca HTTP 429. Aplikacja powinna wtedy wstrzymać kolejne żądanie na czas wskazany w nagłówku Retry-After.
Kolejka żądań ułatwia utrzymanie właściwego tempa automatyzacji¹².

Jak przetestować połączenie z Asana API?

Połączenie można sprawdzić, wysyłając uwierzytelnione żądanie odczytu zasobu dostępnego dla danego konta.
Udane żądanie GET /users/me powinno zwrócić odpowiedź HTTP 200¹³.

• Token dostępu należy umieścić w nagłówku uwierzytelnienia żądania.
• Punkt końcowy trzeba wybrać dla zasobu, do którego konto ma dostęp.
• Kod odpowiedzi warto odczytać wraz z jej treścią, by odróżnić udany odczyt od błędu uwierzytelnienia lub uprawnień.

Udany odczyt zasobu potwierdza połączenie oraz dostęp konta do wybranych danych⁹.

Jak skonfigurować webhooki, by otrzymywać powiadomienia o zmianach w Asanie?

Webhook przypisany do zasobu powiadamia aplikację o zmianach. Aby działał, potrzebuje dostępnego punktu odbioru, potwierdzenia subskrypcji i obsługi przychodzących zdarzeń.
Na żądanie weryfikacyjne serwer musi odpowiedzieć kodem HTTP 200 lub 204 oraz odesłać zgodną wartość nagłówka X-Hook-Secret¹⁴.

• Punkt odbioru HTTPS powinien przyjmować żądania wysyłane przez Asanę.
• Subskrypcję webhooka tworzy się dla wybranego zasobu, podając adres punktu odbioru.
• Żądanie weryfikacyjne wymaga odesłania otrzymanej wartości wskazanego nagłówka.
• Powiadomienia o zmianach trafiają do punktu HTTPS; przed przetworzeniem zdarzenia trzeba zweryfikować ich podpis.
• Dane zasobu należy pobrać przez API, jeśli automatyzacja potrzebuje jego aktualnego stanu po otrzymaniu powiadomienia.

Webhook Asany uruchamia obsługę zmiany bez cyklicznego odpytywania zasobu.
Asana wysyła zdarzenia webhooka żądaniami POST, więc integracja nie musi regularnie wysyłać żądań GET, by wykryć zmiany¹⁴.

Najczęściej zadawane pytania

Gdzie znaleźć klucz API Asany?

Artykuł nie wskazuje, gdzie znaleźć klucz API. Podaje jedynie, że token dostępu należy umieścić w nagłówku uwierzytelnienia żądania.

Jak uzyskać klucz API do Asany?

Artykuł nie opisuje procedury uzyskiwania klucza ani nie wyjaśnia, czy jest on tym samym co token dostępu. Wskazuje, że uwierzytelnione żądania wymagają tokenu dostępu.

Czy Asana udostępnia API?

Tak. Asana API pozwala aplikacjom wymieniać dane z Asaną, między innymi odczytywać i zmieniać zadania.

Jak pobrać dane z Asany?

Wyślij uwierzytelnione żądanie GET do punktu końcowego wybranego zasobu, na przykład /tasks/{task_gid} albo /projects/{project_gid}. Każde z tych żądań zwraca dane jednego wskazanego zasobu.