Uwierzytelnianie w interfejsie API Direct Line 1.1
Ważne
W tym artykule opisano uwierzytelnianie w interfejsie API Direct Line w wersji 1.1. Jeśli tworzysz nowe połączenie między aplikacją kliencką i botem, zamiast tego użyj interfejsu API Direct Line 3.0.
Klient może uwierzytelniać żądania w interfejsie API Direct Line 1.1 przy użyciu wpisu tajnegopozyskanego ze strony konfiguracji kanału Direct Line w portalu Bot Framework lub przy użyciu tokenu uzyskiwanego w czasie wykonywania.
Wpis tajny lub token należy określić w Authorization nagłówku każdego żądania przy użyciu schematu "Bearer" lub schematu "BotConnector".
Schemat elementu nośnego:
Authorization: Bearer SECRET_OR_TOKEN
Schemat BotConnector:
Authorization: BotConnector SECRET_OR_TOKEN
Wpisy tajne i tokeny
Wpis tajny Direct Line to klucz główny, który może służyć do uzyskiwania dostępu do dowolnej konwersacji należącej do skojarzonego bota. Wpis tajny może być również używany do uzyskiwania tokenu. Wpisy tajne nie wygasają.
Token Direct Line jest kluczem, który może służyć do uzyskiwania dostępu do jednej konwersacji. Token wygasa, ale można go odświeżyć.
Jeśli tworzysz aplikację service-to-service, określenie wpisu tajnego w Authorization nagłówku żądań interfejsu API Direct Line może być najprostsze. Jeśli piszesz aplikację, w której klient działa w przeglądarce internetowej lub aplikacji mobilnej, możesz wymienić wpis tajny dla tokenu (który działa tylko dla jednej konwersacji i wygaśnie, chyba że zostanie odświeżony) i określ token w Authorization nagłówku żądań interfejsu API Direct Line. Wybierz model zabezpieczeń, który najlepiej ci odpowiada.
Uwaga
Poświadczenia klienta Direct Line różnią się od poświadczeń bota. Dzięki temu można niezależnie poprawiać klucze i udostępniać tokeny klienta bez ujawniania hasła bota.
Uzyskiwanie wpisu tajnego Direct Line
Wpis tajny Direct Line można uzyskać za pośrednictwem strony konfiguracji kanału Direct Line bota w Azure Portal:
Generowanie tokenu Direct Line
Aby wygenerować token Direct Line, który może służyć do uzyskiwania dostępu do jednej konwersacji, najpierw uzyskaj wpis tajny Direct Line ze strony konfiguracji kanału Direct Line w Azure Portal. Następnie wydaj to żądanie w celu wymiany wpisu tajnego Direct Line dla tokenu Direct Line:
POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer SECRET
Authorization W nagłówku tego żądania zastąp ciąg SECRET wartością wpisu tajnego Direct Line.
Poniższe fragmenty kodu zawierają przykład generowania żądania tokenu i odpowiedzi.
Żądanie
POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Reakcja
Jeśli żądanie zakończy się pomyślnie, odpowiedź zawiera token, który jest prawidłowy dla jednej konwersacji. Token wygaśnie za 30 minut. Aby token pozostał przydatny, należy odświeżyć token przed jego wygaśnięciem.
HTTP/1.1 200 OK
[other headers]
"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn"
Generowanie tokenu a rozpoczynanie konwersacji
Operacja Generowanie tokenu (POST /api/tokens/conversation) jest podobna do operacji Rozpocznij konwersację (POST /api/conversations), w ramach których obie operacje zwracają token wartość , która może służyć do uzyskiwania dostępu do jednej konwersacji. Jednak w przeciwieństwie do operacji Rozpocznij konwersację operacja Generowanie tokenu nie rozpoczyna konwersacji ani nie kontaktuje się z botem.
Jeśli planujesz dystrybuowanie tokenu do klientów i chcesz zainicjować konwersację, użyj operacji Generowanie tokenu. Jeśli zamierzasz natychmiast rozpocząć konwersację, użyj operacji Rozpocznij konwersację .
Odświeżanie tokenu Direct Line
Token Direct Line jest ważny przez 30 minut od momentu jego wygenerowania i może zostać odświeżony nieograniczoną liczbę razy, o ile nie wygasł. Nie można odświeżyć wygasłego tokenu. Aby odświeżyć token Direct Line, wykonaj następujące żądanie:
POST https://directline.botframework.com/api/tokens/{conversationId}/renew
Authorization: Bearer TOKEN_TO_BE_REFRESHED
W identyfikatorze URI tego żądania zastąp ciąg {conversationId} identyfikatorem konwersacji, dla której token jest prawidłowy, a w Authorization nagłówku tego żądania zastąp TOKEN_TO_BE_REFRESHED tokenem Direct Line, który chcesz odświeżyć.
Poniższe fragmenty kodu zawierają przykład żądania i odpowiedzi tokenu odświeżania.
Żądanie
POST https://directline.botframework.com/api/tokens/abc123/renew
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn
Reakcja
Jeśli żądanie zakończy się pomyślnie, odpowiedź zawiera nowy token, który jest ważny dla tej samej konwersacji co poprzedni token. Nowy token wygaśnie za 30 minut. Aby nowy token pozostał przydatny, należy odświeżyć token przed jego wygaśnięciem.
HTTP/1.1 200 OK
[other headers]
"RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0"