De server status van Office 365 ophalen met de Office 365 Service Communications API V2 en PowerShell

Er zijn veel manieren om Office 365 te controleren. Een van die manieren is het Office 365-servicestatusdashboard. Dit dashboard bevindt zich in het Microsoft 365 admin center onder het gedeelte Health en is een geweldige manier om een overzicht te krijgen van Office 365-services. Maar het grafische dashboard laat veel te wensen over wanneer u resources op schaal moet monitoren of die monitoring moet automatiseren.

Microsoft heeft de Office 365 Service Communications API V2 uitgebracht om dit probleem op te lossen. Met deze API kunt u de status van de Office 365-serviceprogramma programmatisch ophalen.

Met deze API met PowerShell-scripting kunt u de controle op wijzigingen in de status van de Office 365-service automatiseren. U kunt uw scripts ontwikkelen om deze statusupdates per e-mail, MS Teams-melding of zelfs naar Slack te verzenden!

In dit artikel leert u hoe u de status van de Office 365-service kunt ophalen met behulp van de Office 365 Service Communications API en PowerShell.

Voorbereiding

Dit artikel loopt door de verschillende stappen. Zorg er voor dat u de volgende van tevoren hebt ingesteld.

  • Een Office 365-tenant. Vraag een proefversie aan als je die nog niet hebt.
  • Een scripteditor, zoals Notepad ++ of een geïntegreerde Scripting Environment (ISE) zoals Windows PowerShell ISE en Visual Studio-code.
  • Windows PowerShell 5.1 of PowerShell Core 6+.
  • Een geregistreerde app in Azure AD met de juiste machtigingen. Raadpleeg Een nieuwe toepassing registreren met Azure Portal als u niet weet hoe u dat moet doen.
  • De geregistreerde app moet de volgende instellingen hebben.

    –         API te gebruiken - Office 365 Management API

    -         API-machtigingen om toe te voegen - ServiceHealth.Read

    –         API-machtigingstype om te selecteren - Toepassingsmachtiging

  • De geregistreerde app moet toestemming van de beheerder hebben gekregen. 
  • De application-id, directory-id en het clientsecretcredential van de geregistreerde app.

De basisprincipes van de API kennen

Als u informatie wilt opvragen via de Office 365 Service Communication API, moet u kennis nemen van de belangrijkste informatie waaruit een aanvraag bestaat.

  • De standaard API-URL die u moet gebruiken, is https://manage.office.com/api/v1.0//ServiceComms.
U vindt de tenant-id in het Azure Active Directory-admin center.
  • Een toegangstoken is vereist. U leert hoe u toegangstokens kunt verkrijgen in de volgende sectie.
  • Het andere pad dat moet worden toegevoegd aan het einde van de API-URL. Dit geeft aan welke informatie wordt opgevraagd. Deze paden zijn:

    -         / Services - Krijgt de lijst met geabonneerde services

    -         /CurrentStatus - Krijg een real-time overzicht van huidige en lopende service-incidenten.

    –         /HistoricalStatus - Geeft als resultaat de historische status van de Office 365-services

    –         /Berichten - Retourneert de berichten over de Office 365-services

    Als u bijvoorbeeld de lijst met services wilt ophalen, wordt de aanvraag-URL https://manage.office.com/api/v1.0//ServiceComms/Services

  • Toegangstokens - Access Tokens verwerven

    Zodra u aan alle vereisten hebt voldaan, is de volgende stap het verkrijgen van het access token ofwel toegangstoken dat wordt gebruikt om de verzoeken te autoriseren.

    Kopieer en plak de onderstaande code in uw scripteditor. Wijzig vervolgens de waarde van de variabelen $TenantID, $ClientID en $ClientSecret met de variabelen uit uw geregistreerde app. Als u deze informatie niet hebt, raadpleegt u deze link om erachter te komen hoe en waar u ze kunt krijgen.

    Nadat u de variabelen hebt bijgewerkt, plakt u de code in uw PowerShell-sessie om deze uit te voeren. De code vraagt om een toegangstoken en slaat de geretourneerde waarde op in de variabele $token.

    # CHANGE THESE VALUES
    $TENANTID = 'TENANT-ID' #THE DIRECTORY ID FROM AZURE AD
    $CLIENTID = 'CLIENT-ID' #THE APPLICATION ID OF THE REGISTERED APP
    $CLIENTSECRET = 'CLIENT-SECRET' #THE SECRET KEY OF THE REGISTERED APP
    # ------------------------------------------------------

    # DO NOT CHANGE THESE
    $BODY = @{GRANT_TYPE="CLIENT_CREDENTIALS";RESOURCE="HTTPS://MANAGE.OFFICE.COM";CLIENT_ID=$CLIENTID;CLIENT_SECRET=$CLIENTSECRET }
    $OAUTH = INVOKE-RESTMETHOD -METHOD POST -URI "HTTPS://LOGIN.MICROSOFTONLINE.COM/$($TENANTID)/OAUTH2/TOKEN?API-VERSION=1.0" -BODY $BODY
    $TOKEN = @{'AUTHORIZATION' = "$($OAUTH.TOKEN_TYPE) $($OAUTH.ACCESS_TOKEN)" }
    # ------------------------------------------------------

    De onderstaande schermafbeelding laat zien hoe de inhoud van het token eruit zou zien.

     

    Inhoud van het access token

    • Aangevraagde access tokens zijn slechts 60 minuten geldig. Zodra het verloopt, moet een nieuw toegangstoken worden aangevraagd.

    De huidige status van de Office 365-service ophalen

    Als u de huidige status van de status ophaalt, krijgt u de realtime status van de Office 365-services in de afgelopen 24 uur.

    Deze commandoregel krijgt een realtime overzicht van huidige en lopende service-incidenten. Kopieer de onderstaande code en plak deze in uw PowerShell-sessie.

    $ServiceStatus = Invoke-RestMethod -Uri "https://manage.office.com/api/v1.0/$($TenantID)/ServiceComms/CurrentStatus" -Headers $token -Method Get -Verbose

    De resultaten van de bovenstaande opdracht die zijn opgeslagen in de variabele $ServiceStatus. Nu kunt u de resultaten weergeven op basis van uw voorkeur. De onderstaande code voert bijvoorbeeld de eigenschappen IncidentID's, WorkloadDisplayName en Status uit.

    $ServiceStatus,prijs-kwaliteitverhouding | Format-Table IncidentIDs,WorkloadDisplayName,Status

     

    Alle beschikbare services weergeven met status- en incident-id's

    De eigenschap WorkloadDisplayName identificeert de naam van elk van de Office 365-services.

    De eigenschap IncidentIds bevat, zoals de naam al aangeeft, de incident-id's die aan elke service zijn gekoppeld. Deze eigenschap wordt meestal ingevuld wanneer de status niet gelijk is aan ServiceOperational. U kunt meer te weten komen over de verschillende statusdefinities door deze link te volgen.

    Berichten over service-incidenten ontvangen

    Microsoft plaatst voortdurend updates voor bestaande of nieuwe incidenten in Office 365-services. Deze berichten kunnen ook worden opgehaald uit de API. Gebruik de onderstaande code om alle berichten over service-incidenten te ontvangen.

    Met de eerste regel wordt de filterreeks gemaakt om de resultaten te filteren op basis van de MessageType-waarde . De opdracht in de tweede regel combineert het API-URL-pad en de filterreeks. En de laatste regel roept het verzoek op.

    Volg deze koppeling om te weten welke andere eigenschapsfilters beschikbaar zijn voor het filteren van berichten.

    $filter = '?$filter=MessageType eq Incident'
    $uri = ("https://manage.office.com/api/v1.0/$($TenantID)/ServiceComms/Messages" + $filter)
    $Messages = Invoke-RestMethod -Uri $uri -Headers $token -Method Get

    De resultaten van de bovenstaande opdracht worden opgeslagen in de variabele $Messages. De opdracht retourneert veel gegevens, u moet de juiste filtering gebruiken om deze correct weer te geven, zoals u in slechts een seconde zult leren.

    In de vorige sectie waarin we de huidige servicestatus opvroegen, is een van de geretourneerde resultaten incident-ID LY197383. We zullen het gebruiken als referentie voor het volgende voorbeeld.

    De onderstaande code filtert de inhoud van de variabele $Messages om alleen de waarde te retourneren waarvan de ID gelijk is aan LY197383.

    $messages. VALUE | Where-Object { $_. Id -eq 'LY197383'} '
    | Select-Object Id,WorkloadDisplayName,Title,StartTime,EndTime,MESSAGES

    De informatie weergeven van specifieke adviezen die zijn uitgebracht voor skype for business service

    Alle updates die door Microsoft zijn uitgebracht met betrekking tot LY197383-advies , worden opgeslagen in de variabele $Messages. Deze variabele bevat de eigenschappen PublishedTime (DateTimeOffset) en MessageText (String) die kunnen worden gebruikt bij het filteren wanneer u de nieuwste update wilt weergeven of de geschiedenis van de service moet backtracken.

    Als u het meest recente bericht van het LY197383-advies voor Skype voor Bedrijven-service wilt bekijken, kopieert/plakt u deze opdrachten hieronder in uw PowerShell-sessie.

    De eerste command line filtert de berichten op basis van het advies Id LY197383 en slaat deze op in $SFB variabele. De tweede opdracht krijgt het totale aantal beschikbare berichten en trekt het af met 1 om de hoogste waarde te krijgen en bewaar het in $msgCount variabele. De derde opdracht gebruikt de waarde van $msgCount variabele om te verwijzen naar de hoogste index in de array die de laatste waarde van het bericht voor het advies bevat.

    $SFB = $MESSAGES.VALUE | WHERE-OBJECT { $_.ID -EQ 'LY197383'}
    [INT]$MSGCOUNT = ($SFB.MESSAGES.COUNT) - 1
    $SFB.MESSAGES[$MSGCOUNT].MESSAGETEXT

    Een resultaat met het laatste bericht van incident-ID LY197383

    De historische status van Office 365-services ophalen

    Het ophalen van de historische status van Office 365-services is handig als u wilt controleren hoe de service in de afgelopen 30 dagen heeft gepresteerd. Het kan u een dagelijks overzicht geven van de status van elke service.

    Deze code hieronder haalt alle historische status op van alle beschikbare Office 365-services. De resultaten worden opgeslagen in de variabele $HistoricalStatus die u later kunt filteren of exporteren.

      $HistoricalStatus = (Invoke-RestMethod -Uri "https://manage.office.com/api/v1.0/$($TenantID)/ServiceComms/HistoricalStatus" -Headers $token -Method Get)

    Zodra u de resultaten hebt, kan deze worden gefilterd om alleen de informatie te krijgen die u relevant acht. In de onderstaande code wordt bijvoorbeeld de historische status van de Skype voor Bedrijven Online-service van de afgelopen 7 dagen weergegeven. De gegevens worden gefilterd met de eigenschappen WorkloadDisplayName en StatusTime .

    $SERVICE = "SKYPE FOR BUSINESS"
    $FILTERDATE = (GET-DATE).ADDDAYS(-7)
    $HISTORICALSTATUS.VALUE | WHERE-OBJECT {$_.WORKLOADDISPLAYNAME -EQ $SERVICE -AND $_.STATUSTIME -GE $FILTERDATE} | SORT-OBJECT STATUSTIME -DESCENDING

    De historische status van de Skype for Business service weergeven

    Samenvatting

    In dit artikel hebt u geleerd hoe u de status van de Office 365-services kunt ophalen met behulp van de Office 365 Service Communications API. U hebt ook geleerd hoe u een access token genereert dat wordt gebruikt om de verzoeken te autoriseren tegen de API.

    U hebt ook gezien hoe u de geretourneerde resultaten van de verschillende typen aanvragen kunt gebruiken, zoals de huidige status, incidentberichten en historische details van elke Office 365-service.

    Ik hoop dat dit artikel u heeft geholpen bij het maken van uw eigen Office 365-servicestatusbewakings- en rapportagescripts. Bedankt voor het lezen!

    Verwijzingen

    De status van de Office 365-service controleren

    Een app registreren in Azure AD

    Naslaginformatie over de Office 365 Service Communications API

     

    Comments
    Comments are disabled in preview mode.