Delen via

Inkomsten beheren met behulp van de Earnings Service-API

In dit artikel wordt uitgelegd hoe u toegang hebt tot inkomstengegevens via de Inkomsten-API's in plaats van de gebruikersinterface van het Partnercentrum. Deze API's bieden een programmatische manier om de functie Gegevens exporteren in partnercentrum te bieden.

Belangrijk

Azure Active Directory (Azure AD) Graph is vanaf 30 juni 2023 afgeschaft. In de toekomst doen we geen verdere investeringen in Azure AD Graph. Azure AD Graph-API's hebben geen SLA of onderhoudsverplichting buiten beveiligingsgerelateerde oplossingen. Investeringen in nieuwe functies en functionaliteiten worden alleen gedaan in Microsoft Graph.

Azure AD Graph wordt in incrementele stappen buiten gebruik gesteld, zodat u voldoende tijd hebt om uw toepassingen te migreren naar Microsoft Graph-API's. Op een later tijdstip dat we zullen aankondigen, blokkeren we het maken van nieuwe toepassingen met behulp van Azure AD Graph.

Zie Belangrijk: Buitengebruikstelling van Azure AD Graph en Afschaffing van Powershell-module voor meer informatie.

Beschikbare API's

Bekijk alle beschikbare API's bij Partner Uitbetalingen.

Vereiste voorwaarden

  • Een werkend abonnement hebben in Azure Portal.
  • Toegang hebben tot een webbrowser.
  • U kunt REST API-aanroepen uitvoeren via programmacode of via toegewezen software.

Een toepassing registreren bij het Microsoft-identiteitsplatform

  1. Volg de instructies voor het maken van een app-registratie met Microsoft Identity Platform.

  2. Geef de app de juiste gedelegeerde machtigingen.

    1. Ga in de zojuist gemaakte app-registratie naar Api-machtigingen beheren →. Selecteer 'Een machtiging toevoegen'. Schermopname van de knop Een machtiging toevoegen.
    2. Selecteer het tabblad API's die mijn organisatie gebruikt en zoek vervolgens de AppId '4990cffe-04e8-4e8b-808a-1175604b879f' of op naam 'Microsoft Dev Center'. Selecteer user_impersonation voor machtigingen. Selecteer Machtigingen toevoegen.
      • Probleemoplossing: Als het zoeken naar de Dev Center-API geen resultaten oplevert, moet u mogelijk de service-principals maken die nodig zijn voor toegang tot deze API's handmatig. Ze kunnen worden gemaakt met AzCLI: 
        az ad sp create --id 4990cffe-04e8-4e8b-808a-1175604b879f
        Daarna moeten de API-machtigingen beschikbaar zijn om te selecteren in het zoekdialoogvenster. Schermopname van de machtiging user_impersonation.
    3. Zorg er bovendien voor dat uw app de machtiging User.Read heeft in Microsoft Graph. Als dit niet het probleem is, voegt u deze toe door Microsoft Graph te selecteren op het tabblad Microsoft API's.
    4. Selecteer 'Beheerderstoestemming verlenen' voor alle drie de machtigingen die u hebt verkregen.
    5. Uw app-machtigingen moeten er als volgt uitzien (let op het groene vinkje naast elke machtiging): Schermopname met de lijst met vereiste machtigingen waaraan beheerderstoestemming is verleend.

  3. Stel een omleidings-URI in voor het webplatform.

    1. Ga naar Beheer → Verificatie. Selecteer 'Een platform toevoegen'. Schermopname van de knop Een platform toevoegen.
    2. Selecteer 'Web'.
    3. Voer in omleidings-URI's bijvoorbeeld de URI in die u wilt gebruiken voor uw toepassing https://localhost:3000. Noteer deze URI voor later gebruik. Druk op Configureren. Schermopname van het tabblad Omleidings-URI's met een voorbeeld-URI van poort 3000 op localhost.

  4. Genereer een clientgeheim dat moet worden gebruikt bij het ophalen van toegangstokens.

    1. Ga naar Beheren → Certificaten en geheimen. Ga naar het tabblad Clientgeheimen en selecteer Nieuw clientgeheim. Schermopname van de knop Een clientgeheim toevoegen.
    2. Voer de gewenste naam en duur in.
    3. Selecteer Geheim toevoegen.
    4. Noteer de waarde ergens anders. Zorg ervoor dat u deze op een veilige locatie bewaart, bijvoorbeeld een sleutelkluis. U gebruikt dit geheim bij het aanvragen van het AccessToken en RefreshToken.

Toegangstoken ophalen - accounts met MFA ingeschakeld

Voor de inkomsten-API's moet een AccessToken worden opgegeven als het autorisatie bearer token in het verzoek, met het voorvoegsel Bearer <access-token> in de autorisatieheader. U kunt dit token verkrijgen door u aan te melden met uw account; Toegangstokens zijn echter kortstondige. Aanmelden bij een account met MFA-functionaliteit om telkens wanneer u de API moet aanroepen, een token te genereren, is niet praktisch voor werkstromen die betrekking hebben op automatisering. Met deze stappen doorloopt u het proces voor het genereren van een RefreshToken. Het heeft een langere levensduur (ongeveer 3 maanden) en kan worden gebruikt om het AccessToken te verkrijgen. Door een RefreshToken op een veilige locatie op te slaan, kunt u dit gebruiken om programmatisch een AccessToken te verkrijgen om de Inkomsten-API aan te roepen. Opmerking: RefreshToken kan slechts eenmaal worden gebruikt, waarna het verouderd wordt. In het antwoord wordt samen met het AccessToken een nieuw RefreshToken geretourneerd. Zorg ervoor dat u de oude waarde van RefreshToken vervangt in uw beveiligde opslag telkens wanneer u een RefreshToken gebruikt.

  1. Haal AuthCode op via de browser. Dit proces moet momenteel worden uitgevoerd met behulp van de gebruikersinterface van een webbrowser en kan niet programmatisch worden uitgevoerd.

    1. Volg de sjabloon hier om een URL te maken die wordt gebruikt om de AuthCode op te halen.
      1. Gebruik tenant-id en client-id voor de gemaakte toepassing.
      2. Stel het bereik in op https://api.partner.microsoft.com/.default.
      3. Stel de omleidings-URL opnieuw in op de geconfigureerde omleidings-URL. De URL-sjabloon is: 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. Ga naar de gegenereerde URL en log in met de inloggegevens van een geautoriseerde gebruiker.
    3. Wanneer u zich hebt aangemeld, probeert uw browser een URL van de indeling <redirect-uri>/?code=<auth-code>&session_state=<state-id>#te openen. Voor het voorbeeld van de omleidings-URI in een vorige stap moet de URL waarnaar u wordt verzonden, zijn https://localhost:3000/?code=<auth-code>?session_state=<state-id>#. Sla de geretourneerde AuthCode ergens veilig op.
      • Omdat er meestal geen app luistert op localhost:3000, krijgt de browser een foutbericht 'kan geen verbinding maken'. Deze fout wordt verwacht, omdat we alleen de AuthCode-waarde handmatig moeten kopiëren uit de code EERDER weergegeven URL-queryparameter.
      • In een prod-oplossing kan een app worden gemaakt die dit deel van het verificatieproces automatisch verwerkt. Het kan bijvoorbeeld een werkstroom zijn waarbij de gebruiker naar een toepassing met één pagina (SPA) gaat. De gebruiker selecteert een knop 'Aanmelden' waarmee deze naar de EERDER gemaakte URL wordt gebracht. Bij het inloggen haalt de SPA de waarde van de AuthCode op en slaat deze op in een kluis. De SPA gebruikt vervolgens de AuthCode om de RefreshToken en AccessToken te verkrijgen, zoals beschreven in de volgende stappen.

  2. Gebruik AuthCode om RefreshToken en eerste AccessToken te verkrijgen. Opmerking: RefreshToken verloopt elke 3 maanden en moet opnieuw worden geplaatst en opgeslagen in een sleutelkluis.

    1. Bouw een POST-API-aanvraag volgens de sjabloon die hier is opgegeven.
      1. Gebruik dezelfde waarden voor tenant-/client-id en omleidings-URL.
      2. Stel het bereik in op https://api.partner.microsoft.com/.default offline_access.
      3. Stel code in op de AuthCode die u in de vorige stap heeft verkregen.
      4. Stel client_secret in op het geheim dat is gegenereerd voor de gemaakte toepassing. De URL moet vervolgens als volgt worden gestructureerd: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

  3. Later kunt u RefreshToken gebruiken om een nieuw AccessToken op te halen.

    1. Bouw een POST-API-aanvraag volgens de sjabloon die hier is opgegeven.
      1. Gebruik dezelfde waarden voor tenant-/client-id en omleidings-URL.
      2. Bereik instellen op https://api.partner.microsoft.com/.default
      3. Stel refresh_token in op het RefreshToken dat u in de vorige stap hebt verkregen
      4. Stel client_secret in op het geheim dat is gegenereerd voor de gemaakte toepassing.

Toegangstoken ophalen - Niet-MFA-accounts

  1. Verkrijg AccessToken met behulp van de informatie voor de nieuwe app-registratie.
    1. Bouw een POST-API-aanvraag volgens de sjabloon die hier is opgegeven.
      1. Dezelfde waarden gebruiken voor tenant-/client-id
      2. Bereik instellen op https://api.partner.microsoft.com/.default
      3. Gebruik de gebruikersnaam/het wachtwoord voor een geautoriseerde gebruiker. De URL moet vervolgens als volgt worden gestructureerd: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
    2. De aanvraag retourneert AccessToken en een nieuw RefreshToken. Zorg ervoor dat u de opgeslagen waarde voor het RefreshToken bijwerkt, omdat u de oude waarde niet meer kunt gebruiken.

Oproepopbrengsten (voorheen transactiegeschiedenis)/Betalingen

Verwante inhoud

  • Last updated on