Earnings Service API를 사용하여 수익 관리

이 문서에서는 파트너 센터 UI 대신 수익 API를 통해 수익 데이터에 액세스하는 방법을 설명합니다. 이러한 API는 파트너 센터에서 데이터 내보내기 기능의 기능을 제공하는 프로그래밍 방식의 방법을 제공합니다.

사용 가능한 API

파트너 지급에서 사용 가능한 모든 API를 참조하세요.

필수 조건

• Azure Portal에서 유효한 구독을 가지고 있습니다.
• 웹 브라우저에 액세스할 수 있습니다.
• 프로그래밍 방식으로 또는 전용 소프트웨어를 통해 REST API를 호출할 수 있습니다.

Microsoft ID 플랫폼에 애플리케이션 등록

1. 지침에 따라 Microsoft ID 플랫폼을 사용하여 앱 등록을 만듭니다.

2. 앱에 적절한 위임된 권한을 부여합니다.

   1. 새로 만든 앱 등록에서 → API 권한 관리로 이동합니다. "권한 추가"를 선택합니다.
   2. "조직에서 사용하는 API" 탭을 선택한 다음 AppId "4990cffe-04e8-4e8b-808a-1175604b879f" 또는 "Microsoft 개발자 센터"를 찾습니다. 사용 권한의 경우 "user_impersonation"을 선택합니다. "권한 추가"를 선택합니다.
      • 문제 해결: 개발자 센터 API 검색 시 결과가 반환되지 않는 경우 이러한 API에 수동으로 액세스하는 데 필요한 서비스 주체를 만들어야 할 수 있습니다. AzCLI를 사용하여 만들 수 있습니다.

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

        그런 다음 검색 대화 상자에서 API 권한을 선택할 수 있어야 합니다.
   3. 그 외에도 앱에 Microsoft Graph의 "User.Read" 권한이 있는지 확인합니다. 그렇지 않으면 Microsoft API 탭에서 Microsoft Graph를 선택하여 추가합니다.
   4. 얻은 세 가지 권한 모두에 대해 "관리자 동의 부여"를 선택합니다.
   5. 앱 사용 권한은 다음과 같이 표시되어야 합니다(각 권한 옆에 녹색 틱 참고):

3. 웹 플랫폼에 대한 리디렉션 URI를 설정합니다.

   1. → 인증 관리로 이동합니다. "플랫폼 추가"를 선택합니다.
   2. "웹"을 선택합니다.
   3. 리디렉션 URI에서 애플리케이션에 대해 사용자 지정하려는 URI를 입력합니다. 예를 들면 다음과 같습니다 https://localhost:3000. 나중에 이 URI를 적어 둡니다. "구성"을 누릅니다.

4. 액세스 토큰을 받을 때 사용할 클라이언트 비밀을 생성합니다.

   1. → 인증서 및 비밀 관리로 이동합니다. "클라이언트 비밀" 탭으로 이동하여 "새 클라이언트 암호"를 선택합니다.
   2. 원하는 이름과 기간을 입력합니다.
   3. 비밀 추가를 선택합니다.
   4. 다른 위치에서 값을 적어둡니다. 키 저장소와 같은 안전한 위치에 보관하십시오. AccessToken 및 RefreshToken을 요청할 때 이 비밀을 사용합니다.

액세스 토큰 가져오기 - MFA 사용 계정

수익 API를 사용하려면 AccessToken 을 권한 부여 헤더의 접두사를 Bearer <access-token> 사용하여 요청에서 권한 부여 전달자 토큰으로 제공해야 합니다. 계정으로 로그인하여 이 토큰을 가져올 수 있습니다. 그러나 액세스 토큰은 수명이 짧습니다. API를 호출해야 할 때마다 토큰을 생성하기 위해 MFA 사용 계정에 로그인하는 것은 자동화와 관련된 워크플로에 적합하지 않습니다. 다음 단계에서는 RefreshToken을 생성하는 프로세스를 안내합니다. 수명이 더 길고(약 3개월) AccessToken을 가져오는 데 사용할 수 있습니다. RefreshToken을 안전한 위치에 저장하면 이를 사용하여 프로그래밍 방식으로 AccessToken을 가져와서 수익 API를 호출할 수 있습니다. 참고: RefreshToken 은 한 번만 사용할 수 있으며 그 후에는 사용되지 않습니다. 응답에서 새 RefreshToken 이 AccessToken과 함께 반환됩니다. RefreshToken을 사용할 때마다 보안 스토리지에 있는 RefreshToken의 이전 값을 바꿔야 합니다.

1. 브라우저를 통해 AuthCode를 가져옵니다. 현재 이 프로세스는 웹 브라우저의 UI를 사용하여 수행해야 하며 프로그래밍 방식으로 수행할 수 없습니다.

   1. 여기에서 템플릿을 따라 AuthCode를 검색하는 데 사용되는 URL을 빌드합니다.
      1. 만든 애플리케이션에 테넌트 ID 및 클라이언트 ID를 사용합니다.
      2. https://api.partner.microsoft.com/.default로 범위를 설정합니다.
      3. 이전에 구성된 리디렉션 URL로 리디렉션 URL을 설정합니다. URL 템플릿은 다음과 같습니다. 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. 빌드된 URL로 이동하여 권한 있는 사용자의 자격 증명을 사용하여 로그인합니다.
   3. 로그인에 성공하면 브라우저에서 형식 <redirect-uri>/?code=<auth-code>&session_state=<state-id>#의 URL을 열려고 시도합니다. 이전 단계의 리디렉션 URI 예제에서, 당신이 이동하게 되는 URL은 https://localhost:3000/?code=<auth-code>?session_state=<state-id>#입니다. 반환된 AuthCode를 안전한 곳에 저장합니다.
      • 일반적으로 localhost:3000에서 수신 대기하는 앱이 없으므로 브라우저는 "연결할 수 없습니다"라는 오류 메시지를 제공합니다. 이전에 표시된 URL 쿼리 매개 변수에서 code AuthCode 값을 수동으로 복사하기만 하면 되므로 이 오류가 예상됩니다.
      • prod 솔루션에서는 인증 프로세스의 이 부분을 자동으로 처리하는 앱을 만들 수 있습니다. 예를 들어 사용자가 SPA(단일 페이지 애플리케이션)로 가는 워크플로일 수 있습니다. 사용자는 이전에 생성된 URL로 이동되는 "로그인" 단추를 선택합니다. 로그인 시 SPA는 AuthCode 값을 추출하여 보관소에 저장합니다. 그런 다음 SPA는 AuthCode를 사용하여 다음 단계에서 설명한 대로 RefreshToken 및 AccessToken을 가져옵니다.

2. AuthCode를 사용하여 RefreshToken 및 초기 AccessToken을 가져옵니다. 참고: RefreshToken 은 3개월마다 만료되며 다시 획득하여 일부 키 보관소에 저장해야 합니다.

   1. 여기에 제공된 템플릿에 따라 POST API 요청을 빌드 합니다.
      1. 테넌트/클라이언트 ID 및 리디렉션 URL에 대해 동일한 값을 사용합니다.
      2. 범위를 https://api.partner.microsoft.com/.default offline_access로 설정합니다.
      3. 이전 단계에서 가져온 AuthCode로 코드를 설정합니다.
      4. client_secret 만든 애플리케이션에 대해 생성된 비밀로 설정합니다. 그런 다음 URL을 다음과 같이 구성해야 합니다. https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

3. 나중에 RefreshToken 을 사용하여 새 AccessToken을 가져올 수 있습니다.

   1. 여기에 제공된 템플릿에 따라 POST API 요청을 빌드 합니다.
      1. 테넌트/클라이언트 ID 및 리디렉션 URL에 대해 동일한 값을 사용합니다.
      2. https://api.partner.microsoft.com/.default로 범위 설정하다
      3. 이전 단계에서 가져온 RefreshToken으로 refresh_token 설정
      4. client_secret 만든 애플리케이션에 대해 생성된 비밀로 설정합니다.

액세스 토큰 가져오기 - MFA가 아닌 계정

1. 새 앱 등록에 대한 정보를 사용하여 AccessToken 을 가져옵니다.
   1. 여기에 제공된 템플릿에 따라 POST API 요청을 빌드 합니다.
      1. 테넌트/클라이언트 ID에 동일한 값 사용
      2. 범위를 https://api.partner.microsoft.com/.default로 설정
      3. 권한 있는 사용자에 대해 사용자 이름/암호를 사용합니다. URL은 다음과 같이 구성되어야 합니다. https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
   2. 요청은 AccessToken 및 새 RefreshToken을 반환합니다. 이전 값을 더 이상 사용할 수 없으므로 RefreshToken에 저장된 값을 업데이트해야 합니다.

통화 수익(이전의 트랜잭션 기록)/결제

• 이전에 권한 부여 헤더에서 얻은 AccessToken 을 접두사 Bearer <access-token> 로 사용하여 새 수익(이전의 트랜잭션 히스토리) 또는 결제 보고서를 만듭니다.

관련 콘텐츠

• 포털을 사용하여 리소스에 액세스할 수 있는 Microsoft Entra 애플리케이션 및 서비스 주체 만들기
• Microsoft ID 플랫폼을 사용하여 애플리케이션 등록
• 웹 API에 액세스하도록 클라이언트 애플리케이션 구성