AI Engine działa w modelu „bring your own key”: to Ty masz konto u dostawcy AI i klucz API. Klucz jest przechowywany we własnym magazynie poświadczeń Salesforce, a nie w AI Engine. Ten artykuł wyjaśnia, jak to działa i jak zarządzać kluczem. Kroki pierwszej konfiguracji znajdziesz w artykule Połącz dostawcę AI.
Gdzie znajduje się klucz#
Salesforce dzieli połączenie z dostawcą na dwie części:
- External Credential przechowuje sekret. Klucz API jest wysyłany w niestandardowym nagłówku zdefiniowanym w External Credential (zobacz tabelę poniżej).
- Named Credential przechowuje URL dostawcy i wskazuje na External Credential.
W Org Profile wpisujesz tylko nazwę Named Credential. AI Engine wywołuje dostawcę przez tę nazwę, a Salesforce dodaje klucz do żądania w momencie jego wysyłania. W rezultacie:
- Klucz nie jest przechowywany w kodzie, ustawieniach ani rekordach AI Engine i nie pojawia się w panelu administratora.
- Użytkownicy AI Engine nie widzą klucza. Każdy, kto może wyświetlić External Credential w Setup, może zobaczyć klucz wpisany bezpośrednio w wartość nagłówka, dlatego zapoznaj się ze wskazówką poniżej.
- Cloud Connected nie otrzymuje Twojego klucza i nikt w Cloud Connected ani u partnera go nie potrzebuje. Zachowaj go w obrębie własnego zespołu.
| Dostawca | URL Named Credential | Nagłówek z kluczem w External Credential |
|---|---|---|
| OpenAI | https://api.openai.com |
Authorization = Bearer YOUR_KEY |
| Anthropic | https://api.anthropic.com |
x-api-key = YOUR_KEY |
| Azure OpenAI | https://YOUR_RESOURCE.openai.azure.com |
api-key = YOUR_KEY |
Wskazówka: nie pokazuj klucza w Setup. Zamiast wpisywać klucz w wartość nagłówka:
- Dodaj klucz jako parametr uwierzytelniania (na przykład
ApiKey) w principalu External Credential. - Ustaw wartość nagłówka jako formułę, która się do niego odwołuje, na przykład
{!'Bearer ' & $Credential.YOUR_EXTERNAL_CREDENTIAL.ApiKey}dla OpenAI. - W Named Credential zaznacz Allow Formulas in HTTP Header.
Salesforce przechowuje parametry principala w postaci zaszyfrowanej i nie wyświetla ich po zapisaniu.
Kto może używać poświadczenia#
Aby żądanie użytkownika dotarło do dostawcy, muszą być spełnione trzy warunki. Skonfiguruj je w tej kolejności:
- Zezwól pakietowi na używanie Named Credential. AI Engine jest pakietem zarządzanym (managed package) w przestrzeni nazw
CloudConnected. W Setup → Named Credentials edytuj Named Credential i w sekcji Managed Package Callout Allowlist wpiszCloudConnectedw polu Allowed Namespaces for Callouts. Zapisz. - Nadaj dostęp do principala. Każdy, kto korzysta z AI Engine, łącznie z administratorami, potrzebuje dostępu do principala External Credential. Spakowane permission sety AI Engine pochodzą z pakietu zarządzanego, więc użyj własnego permission setu: w Setup → Permission Sets otwórz go lub utwórz, przejdź do External Credential Principal Access, kliknij Edit, dodaj principal, zapisz i przypisz permission set tym samym użytkownikom. Zobacz Połącz dostawcę AI, krok 3.
- Sprawdź dostęp Read do User External Credentials. Salesforce wymaga go do wykonania calloutu. Permission set AI Engine User już go zawiera; jeśli używasz sklonowanego permission setu, dodaj go tam.
Jeśli brakuje któregoś z tych elementów, żądania AI kończą się błędem nawet u użytkowników, którzy mają permission sety AI Engine. Zobacz sekcję „Rozwiązywanie problemów” poniżej.
Rotacja klucza#
Przy planowanej rotacji unikniesz przestoju, jeśli stary i nowy klucz będą przez pewien czas działać równolegle:
- Utwórz nowy klucz na koncie u dostawcy. Nie unieważniaj jeszcze starego.
- W Salesforce otwórz External Credential i zastąp klucz: w wartości niestandardowego nagłówka albo w parametrze uwierzytelniania principala, jeśli zastosowano wskazówkę powyżej. Zachowaj tę samą nazwę Named Credential, aby Org Profile nie wymagał zmian.
- Przetestuj na koncie zwykłego użytkownika, nie tylko jako administrator: zadaj pytanie w czacie i uruchom jedną akcję na rekordzie, na przykład Next Steps.
- Gdy oba testy działają, unieważnij stary klucz na koncie u dostawcy.
Jeśli podejrzewasz, że klucz wyciekł, najpierw unieważnij go u dostawcy, akceptując krótką przerwę w działaniu, a następnie utwórz nowy klucz i dodaj go w Salesforce.
Miej w gotowości drugiego dostawcę#
Zmiana dostawcy to zmiana konfiguracji: w Org Profile w panelu administratora wybierz inne wartości AI Provider, AI Model, Fast model (internal steps) i Named Credential, a następnie kliknij Save. Szybki model musi należeć do tego samego dostawcy co Named Credential. Utrzymywanie drugiego, skonfigurowanego i przetestowanego Named Credential pozwala przełączyć się w ciągu kilku minut, jeśli główny dostawca ma awarię. Testuj go ponownie po każdej rotacji klucza.
Rozwiązywanie problemów#
„AI provider returned an error. Please try again or contact your administrator.” Użytkownicy widzą ten komunikat, gdy dostawca odrzuca żądanie, na przykład z kodem 401 Unauthorized, ponieważ klucz jest nieprawidłowy, wygasł lub został unieważniony. Sprawdź wartość nagłówka w External Credential oraz to, czy klucz jest nadal aktywny na koncie u dostawcy.
„AI provider access is not configured for your user.” Użytkownik nie może korzystać z poświadczenia. Sprawdź, czy jeden z jego permission setów nadaje dostęp do principala i czy użytkownik ma dostęp Read do User External Credentials.
„AI provider is not configured.” Nazwa Named Credential w Org Profile nie jest dokładnie taka sama jak w Setup (wielkość liter ma znaczenie), poświadczenie nie istnieje albo w jego polu Allowed Namespaces for Callouts brakuje CloudConnected.
Więcej: