Control API - środowiska
Użyj FoxIDs Control API, aby wyświetlić, utworzyć, skonfigurować i usunąć środowiska w tenant. Środowisko nazywa się track w Control API trasach i schematach.
Przed wywołaniem tych operacji skonfiguruj Control API uwierzytelnianie i prawa dostępu. Swagger pozostaje dokładnym odniesieniem do wszystkich właściwości środowiska, reguł sprawdzania poprawności i schematów odpowiedzi:
Baza punktów końcowych
Administrowanie środowiskiem odbywa się poprzez środowisko master urządzenia tenant. W przykładach zastosowano FoxIDs Cloud:
https://control.foxids.com/api/{tenant_name}/master
Zamień {tenant_name} na nazwę techniczną tenant. Zmień hosta dla wdrożenia samodzielnego. Wyślij token dostępu Control API w nagłówku Authorization: Bearer {access_token}.
Operacje w środowisku wymagają odpowiedniego prawa dostępu tenant lub środowiska. Środowiska zwracane przez operacje na listach są ograniczone do tych, do których obiekt wywołujący może uzyskać dostęp. Użyj Control API hierarchii praw dostępu, aby przyznać tylko wymaganą operację read, create, update lub delete.
Operacje środowiskowe
Operacje środowiskowe są pogrupowane w sekcji tenant tracks w Swagger.
| Działanie | Punkt końcowy | Zamiar |
|---|---|---|
| Lista | GET /!tracks |
Wyświetl listę dostępnych środowisk z opcjonalnym filtrowaniem i paginacją. |
| Dostawać | GET /!track?name={name} |
Uzyskaj pełną konfigurację dla jednego środowiska. |
| Tworzyć | POST /!track |
Utwórz środowisko i jego domyślną metodę uwierzytelniania logowania. |
| Aktualizacja | PUT /!track |
Zastąp edytowalną konfigurację środowiska. |
| Usuwać | DELETE /!track?name={name} |
Trwale usuń środowisko i jego dane. |
Dołącz każdy punkt końcowy do bazy punktu końcowego.
Wymień i zidentyfikuj środowiska
GET /!tracks akceptuje filterName i paginationToken. Filtr odpowiada parametrowi technicznemu name lub displayName, bez względu na wielkość liter.
Odpowiedź zawiera kolekcję data i nieprzezroczystą paginationToken. Aby przeczytać następną stronę, powtórz to samo żądanie ze zwróconym tokenem i tym samym filtrem. Kontynuuj, aż odpowiedź nie będzie już zawierać tokenu. Nie interpretuj ani nie modyfikuj tokena.
Techniczny name identyfikuje środowisko w Control API adresach URL oraz w kolejnych operacjach pobierania, aktualizacji i usuwania. Traktuj go jak stabilny klucz do automatyzacji. Użyj displayName w przypadku tekstu prezentowanego administratorom.
Stwórz środowisko
Nazwy środowisk pisane są małymi literami. Podaj name, gdy integracja wymaga przewidywalnego adresu URL, lub pomiń go i pozwól, aby FoxIDs wygenerowało unikalną nazwę. Żądanie musi zawierać nazwę lub nazwę wyświetlaną.
Utworzenie środowiska powoduje również utworzenie domyślnej metody uwierzytelniania logowania. Inne aplikacje, metody uwierzytelniania, użytkownicy, klucze i zasoby środowiska są konfigurowane oddzielnie po utworzeniu.
Plan tenant może ograniczać liczbę środowisk. Dlatego żądanie utworzenia może zakończyć się niepowodzeniem po osiągnięciu limitu. Współbieżne operacje tworzenia ograniczone planem mogą zwrócić 423 Locked; spróbuj ponownie po krótkim opóźnieniu.
Zaktualizuj ustawienia środowiska
PUT /!track to pełna aktualizacja, a nie łatka. Najpierw pobierz bieżące środowisko, zachowaj wszystkie właściwości, które powinny pozostać niezmienione, zastosuj zamierzone zmiany i wyślij kompletną, edytowalną reprezentację.
Techniczny name wybiera środowisko i aktualizacja nie zmienia jego nazwy. Edytowalne ustawienia obejmują szczegóły wyświetlania i firmy, czas życia sekwencji, zachowanie mapowania roszczeń, ochronę przed błędami logowania, zasady haseł, integrację haseł zewnętrznych i katalogów oraz dozwolone domeny iframe. Niektóre powiązane zasoby, w tym SMS-y, e-maile, mapowania roszczeń, SMS-y, klucze i certyfikaty, mają dedykowane punkty końcowe i nie są zastępowane przez działanie środowiska.
Zaktualizowane ustawienia są używane przez kolejne żądania po tym, jak FoxIDs unieważni pamięć podręczną konfiguracji środowiska.
Usuń środowisko
Usuwanie środowiska jest operacją nieodwracalną i kaskadową. Usuwa konfigurację środowiska i wszystkie dane należące do tego środowiska, w tym jego aplikacje, metody uwierzytelniania, użytkowników, sesje, dotacje, klucze i inne zasoby. Linki z innych środowisk do usuniętego środowiska również zostaną usunięte.
Nie używaj usuwania środowiska jako sposobu na wyczyszczenie wybranych zasobów. Usuń lub zaktualizuj te zasoby indywidualnie, gdy środowisko musi pozostać dostępne. Przed usunięciem środowiska zatrzymaj ruch do niego, wyeksportuj konfigurację lub dane, które muszą zostać zachowane, i zweryfikuj nazwę techniczną w żądaniu.
Wskazówki dotyczące automatyzacji
- Zachowaj stabilność nazw technicznych i przechowuj je oddzielnie od nazw wyświetlanych.
- Użyj paginacji listy, nawet jeśli tenant ma obecnie tylko kilka środowisk.
- Użyj przepływu pracy pobierz-modyfikuj-wstaw, aby uniknąć niezamierzonego resetowania ustawień dodanych w nowszej wersji FoxIDs.
- Utwórz zasoby zależne dopiero po pomyślnym przesłaniu żądania utworzenia środowiska.
- Traktuj usuwanie jako operację trwałego usunięcia i wymagaj wyraźnego potwierdzenia w narzędziach administracyjnych.
- Oczekuj, że żądania tworzenia, aktualizacji i usuwania pojawią się w dzienniku audytu kontroli. Operacje odczytu nie są zapisywane jako zdarzenia kontroli.
Typowe reakcje na błędy
400 Bad Request, gdy dane lub nazwa środowiska są nieprawidłowe, używana jest zastrzeżona nazwa lub osiągnięto limit planu.401 Unauthorized, gdy brakuje tokena dostępu lub jest on nieprawidłowy.403 Forbidden, gdy wywołujący nie ma wymaganych uprawnień dostępu.404 Not Found, gdy wybrane środowisko nie istnieje.409 Conflict, gdy istnieje już środowisko o tej samej nazwie technicznej.423 Locked, gdy operacja tworzenia ograniczona planem jest tymczasowo zablokowana.
Użyj treści odpowiedzi, aby uzyskać szczegółowe informacje dotyczące sprawdzania poprawności, oraz Swagger UI w przypadku odpowiedzi zadeklarowanych przez każdą operację.