Zarządzanie zarobkami przy użyciu interfejsu API usługi Zarobków

W tym artykule wyjaśniono, jak uzyskać dostęp do danych zarobków za pośrednictwem API zarobków zamiast konsoli Centrum partnerskiego. Te interfejsy API zapewniają programowy sposób zapewniania możliwości funkcji Eksportowanie danych w Centrum partnerskim.

Dostępne interfejsy API

Zobacz wszystkie dostępne interfejsy API na stronie Wypłaty partnerów.

Wymagania wstępne

• Masz działającą subskrypcję w witrynie Azure Portal.
• Mieć dostęp do przeglądarki internetowej.
• Możliwość tworzenia wywołań interfejsu API REST programowo lub za pomocą dedykowanego oprogramowania.

Rejestrowanie aplikacji za pomocą platformy tożsamości firmy Microsoft

1. Postępuj zgodnie z instrukcjami, aby utworzyć rejestrację aplikacji za pomocą platformy tożsamości firmy Microsoft.

2. Nadaj aplikacji odpowiednie uprawnienia delegowane.

   1. W nowo utworzonej rejestracji aplikacji przejdź do pozycji Zarządzanie uprawnieniami interfejsu API →. Wybierz pozycję "Dodaj uprawnienie".
   2. Wybierz kartę "Interfejsy API używane przez moją organizację", a następnie wyszukaj identyfikator AppId "4990cffe-04e8-4e8b-808a-1175604b879f" lub według nazwy "Microsoft Dev Center". Aby uzyskać uprawnienia, wybierz pozycję "user_impersonation". Wybierz pozycję "Dodaj uprawnienia".
      • Rozwiązywanie problemów: jeśli wyszukiwanie interfejsu API Centrum deweloperów nie zwraca żadnych wyników, może być konieczne utworzenie jednostek usługi wymaganych do ręcznego uzyskiwania dostępu do tych interfejsów API. Można je utworzyć za pomocą polecenia AzCLI:

        az ad sp create --id 4990cffe-04e8-4e8b-808a-1175604b879f
        

        Następnie uprawnienia interfejsu API powinny być dostępne do wybrania w oknie dialogowym wyszukiwania.
   3. Upewnij się, że aplikacja ma uprawnienie "User.Read" w programie Microsoft Graph. Jeśli tak nie jest, dodaj go, wybierając pozycję Microsoft Graph na karcie Interfejsy API firmy Microsoft.
   4. Wybierz pozycję "Udziel zgody administratora" dla wszystkich trzech uzyskanych uprawnień.
   5. Uprawnienia aplikacji powinny wyglądać następująco (zwróć uwagę na zielony znacznik obok każdego uprawnienia):

3. Skonfiguruj identyfikator URI przekierowania dla platformy sieci Web.

   1. Przejdź do pozycji Zarządzanie uwierzytelnianiem →. Wybierz pozycję "Dodaj platformę".
   2. Wybierz pozycję "Sieć Web".
   3. W polu Adresy URI przekierowania wprowadź URI, którego zamierzasz użyć dla aplikacji, na przykład https://localhost:3000. Zanotuj ten identyfikator URI do późniejszego użycia. Naciśnij "Konfiguruj".

4. Wygeneruj klucz tajny klienta do użycia podczas uzyskiwania tokenów dostępu.

   1. Przejdź do Zarządzanie → Certyfikaty i sekrety. Przejdź do karty "Wpisy tajne klienta", wybierz pozycję "Nowy klucz tajny klienta".
   2. Wprowadź żądaną nazwę i czas trwania.
   3. Wybierz pozycję Dodaj wpis tajny.
   4. Zanotuj wartość w innym miejscu. Pamiętaj, aby zachować ją w bezpiecznej lokalizacji, na przykład w magazynie kluczy. Tajna wartość jest używana podczas żądania tokenu AccessToken i RefreshToken.

Uzyskiwanie tokenu dostępu — konta z obsługą uwierzytelniania wieloskładnikowego

Interfejsy API zarobków wymagają podania AccessToken jako tokenu uwierzytelniającego typu Bearer w żądaniu, z odpowiednim prefiksem Bearer <access-token> w nagłówku autoryzacji. Ten token można uzyskać, logując się przy użyciu konta; jednak tokeny dostępu są krótkotrwałe. Logowanie się do konta z obsługą uwierzytelniania wieloskładnikowego w celu wygenerowania tokenu za każdym razem, gdy musisz wywołać interfejs API, nie jest praktyczne w przypadku przepływów pracy obejmujących automatyzację. Te kroki przeprowadzą Cię przez proces generowania tokenu RefreshToken. Ma dłuższą żywotność (około 3 miesięcy) i może służyć do uzyskania tokenu AccessToken. Przechowując token RefreshToken w bezpiecznej lokalizacji, można go użyć do programowego uzyskania tokenu AccessToken w celu wywołania interfejsu API zarobków. Uwaga: token RefreshToken może być używany tylko raz, po czym staje się przestarzały. W odpowiedzi zostanie zwrócony nowy RefreshToken wraz z AccessToken. Pamiętaj, aby zastąpić starą wartość RefreshToken w bezpiecznym magazynie za każdym razem, gdy używasz RefreshToken.

1. Pobierz kod AuthCode za pośrednictwem przeglądarki. Obecnie ten proces należy wykonać przy użyciu interfejsu użytkownika przeglądarki internetowej i nie można wykonać go programowo.

   1. Postępuj zgodnie z szablonem tutaj , aby utworzyć adres URL używany do pobierania kodu AuthCode.
      1. Użyj identyfikatora dzierżawy i identyfikatora klienta dla utworzonej aplikacji.
      2. Ustaw zakres na https://api.partner.microsoft.com/.default.
      3. Ustaw adres URL na wcześniej skonfigurowany adres URL przekierowania. Szablon adresu URL to: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize?client_id=<client-id>&response_type=code&redirect_uri=<redirect-uri>&scope=https%3A%2F%2Fapi.partner.microsoft.com%2F.default
   2. Przejdź do wbudowanego adresu URL i zaloguj się przy użyciu poświadczeń autoryzowanego użytkownika.
   3. Po pomyślnym zalogowaniu przeglądarka próbuje otworzyć adres URL w formacie <redirect-uri>/?code=<auth-code>&session_state=<state-id>#. W przykładzie identyfikatora URI przekierowania w poprzednim kroku, adres URL, do którego zostaniesz wysłany, powinien być https://localhost:3000/?code=<auth-code>?session_state=<state-id>#. Zapisz zwrócony kod AuthCode gdzieś bezpieczny.
      • Ponieważ zwykle nie ma aplikacji nasłuchującej na hoście lokalnym:3000, przeglądarka wyświetla komunikat o błędzie "nie można nawiązać połączenia". Ten błąd jest oczekiwany, ponieważ wystarczy ręcznie skopiować wartość AuthCode z podanego wcześniej parametru code zapytania adresu URL.
      • W rozwiązaniu prod można utworzyć aplikację, która automatycznie obsługuje tę część procesu uwierzytelniania. Na przykład może to być przepływ pracy, w którym użytkownik przechodzi do aplikacji jednostronicowej (SPA). Użytkownik wybiera przycisk "zaloguj się", który przenosi go do wcześniej skonstruowanego adresu URL. Po zalogowaniu SPA wyodrębnia wartość AuthCode i zapisuje ją w sejfie. SPA następnie używa AuthCode do uzyskania RefreshToken i AccessToken zgodnie z opisem w następnych krokach.

2. Użyj AuthCode , aby uzyskać RefreshToken i początkowy AccessToken. Uwaga: RefreshToken wygasa co 3 miesiące i musi zostać ponownie uzyskany oraz zapisany w magazynie kluczy.

   1. Skompiluj żądanie interfejsu API POST zgodnie z szablonem podanym tutaj.
      1. Użyj tych samych wartości dla identyfikatora dzierżawcy/klienta i URL przekierowania.
      2. Ustaw zakres na https://api.partner.microsoft.com/.default offline_access.
      3. Ustaw kod na AuthCode uzyskany w poprzednim kroku.
      4. Ustaw client_secret na sekret wygenerowany dla stworzonej aplikacji. Adres URL powinien być następnie ustrukturyzowany w następujący sposób: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

3. Później możesz użyć metody RefreshToken , aby uzyskać nowy token AccessToken.

   1. Skompiluj żądanie interfejsu API POST zgodnie z szablonem podanym tutaj.
      1. Użyj tych samych wartości dla identyfikatora najemcy/klienta i adresu URL przekierowania.
      2. Ustaw zakres na https://api.partner.microsoft.com/.default
      3. Ustaw refresh_token na token odświeżania uzyskany w poprzednim kroku
      4. Ustaw client_secret na sekret wygenerowany dla utworzonej aplikacji.

Token dostępu - konta bez MFA

1. Uzyskaj token AccessToken , korzystając z informacji dotyczących rejestracji nowej aplikacji.
   1. Skompiluj żądanie interfejsu API POST zgodnie z szablonem podanym tutaj.
      1. Użyj tych samych wartości dla identyfikatora dzierżawy/klienta
      2. Ustaw zakres na https://api.partner.microsoft.com/.default
      3. Użyj nazwy użytkownika/hasła dla autoryzowanego użytkownika Adres URL powinien być ustrukturyzowany w następujący sposób: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
   2. Żądanie zwraca AccessToken i nowy RefreshToken. Pamiętaj, aby zaktualizować przechowywaną wartość dla tokenu RefreshToken, ponieważ nie można już używać starej wartości.

Zarobki z połączeń (dawniej historia transakcji)/Płatności

• Użyj tokenu AccessToken uzyskanego wcześniej w nagłówku Autoryzacja z prefiksem Bearer <access-token> , aby utworzyć nowe raporty Zarobki (dawniej transactionhistory) lub Płatności .

Treści powiązane

• Użyj portalu, aby utworzyć aplikację Firmy Microsoft Entra i jednostkę usługi, która może uzyskiwać dostęp do zasobów
• Rejestrowanie aplikacji za pomocą platformy tożsamości firmy Microsoft
• Konfigurowanie aplikacji klienckiej w celu uzyskania dostępu do internetowego interfejsu API