servicePrincipal を取得する

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

servicePrincipal オブジェクトのプロパティとリレーションシップを取得します。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。

アクセス許可の種類 最小特権アクセス許可 特権の高いアクセス許可
委任 (職場または学校のアカウント) Application.Read.All Application.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All
委任 (個人用 Microsoft アカウント) サポートされていません。 サポートされていません。
アプリケーション Application.Read.All Application.ReadWrite.OwnedBy、Application.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All

注:

サービス プリンシパルは、アプリケーションのアクセス許可を付与されていなくても、独自のアプリケーションとサービス プリンシパルの詳細を取得できます。 Application.ReadWrite.OwnedBy アクセス許可を使用すると、アプリがテナント内のすべてのアプリケーションとサービス プリンシパルを呼び出してGET /applicationsGET /servicePrincipals一覧表示できます。 このアクセス範囲は、アクセス許可に対して許可されています。

HTTP 要求

サービス プリンシパルは、 その ID または appId を使用してアドレス指定できます。 id と appId は、Microsoft Entra 管理センターのアプリ登録でそれぞれオブジェクト ID とアプリケーション (クライアント) ID と呼ばれます。

GET /servicePrincipals/{id}
GET /servicePrincipals(appId='{appId}')

オプションのクエリ パラメーター

このメソッドは、応答をカスタマイズするための $select および $expandOData クエリ パラメーターをサポートします。

このメソッドは、応答のカスタマイズに$count$filter$expand$orderby役立つ、、$search、$select、および$top OData クエリ パラメーターをサポートします。 クエリの中には、ConsistencyLevel ヘッダーの設定を eventual および $count に使用した場合にのみサポートされるものもあります。 詳細については、「ディレクトリ オブジェクトの詳細クエリ機能」を参照してください。

keyCredentials が$selectクエリで指定されていない限り、既定では、この API は keyCredentialプロパティのキー の公開キー値を返しません。 たとえば、$select=id,appId,keyCredentials などです。

アプリケーションで $select を使用して keyCredentials を取得するには、テナントごとに 1 分あたり 150 要求の調整制限があります。

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。
Accept-Language 言語コード。 省略可能。

Accept-Language ヘッダーに対応した言語コード、例えば es-ES or de-DE を指定すると、利用可能な場合はローカライズされた値が返されます。 ヘッダーは、リスト操作ではサポートされていないことに注意してください。

要求本文

このメソッドには、要求本文を指定しません。

応答

成功した場合、このメソッドは 200 OK 応答コードと、応答本文で servicePrincipal オブジェクトを返します。

例

例 1: 指定したサービス プリンシパルのプロパティを取得する

要求

次の例は要求を示しています。

GET https://graph.microsoft.com/beta/servicePrincipals/{id}

応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 200 OK
Content-type: application/json

{
        "id": "59e617e5-e447-4adc-8b88-00af644d7c92",
        "deletedDateTime": null,
        "accountEnabled": true,
        "appDisplayName": "My App",
        "appId": "65415bb1-9267-4313-bbf5-ae259732ee12",
        "applicationTemplateId": null,
        "appOwnerOrganizationId": "1bc1c026-2f7b-48a5-98da-afa2fd8bc7bc",
        "appRoleAssignmentRequired": false,
        "disabledByMicrosoftStatus": null,
        "displayName": "foo",
        "errorUrl": null,
        "homepage": null,
        "loginUrl": null,
        "logoutUrl": null,
        "notificationEmailAddresses": [],
        "preferredSingleSignOnMode": null,
        "preferredTokenSigningKeyEndDateTime": null,
        "preferredTokenSigningKeyThumbprint": null,
        "publisherName": "Contoso",
        "replyUrls": [],
        "samlMetadataUrl": null,
        "samlSingleSignOnSettings": null,
        "servicePrincipalNames": [
            "f1bd758f-4a1a-4b71-aa20-a248a22a8928"
        ],
        "signInAudience": "AzureADandPersonalMicrosoftAccount",
        "tags": [],
        "verifiedPublisher": {
            "displayName": "publisher_contoso",
            "verifiedPublisherId": "9999999",
             "addedDateTime": "2021-04-24T17:49:44Z"
        },
        "addIns": [],
        "api": {
            "resourceSpecificApplicationPermissions": []
        },
        "appRoles": [],
        "info": {
            "termsOfServiceUrl": null,
            "supportUrl": null,
            "privacyStatementUrl": null,
            "marketingUrl": null,
            "logoUrl": null
        },
        "keyCredentials": [],
        "publishedPermissionScopes": [],
        "passwordCredentials": []
}

例 2: appId と特定のプロパティのみを使用してサービス プリンシパルを取得する

要求

次の例は要求を示しています。

GET https://graph.microsoft.com/beta/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')?$select=id,appId,displayName,appRoles,publishedPermissionScopes,resourceSpecificApplicationPermissions

応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(id,appId,displayName,appRoles,publishedPermissionScopes)/$entity",
    "id": "7408235b-7540-4850-82fe-a5f15ed019e2",
    "appId": "00000003-0000-0000-c000-000000000000",
    "displayName": "Microsoft Graph",
    "appRoles": [
        {
            "allowedMemberTypes": [
                "Application"
            ],
            "description": "Allows the app to read all class assignments without grades for all users without a signed-in user.",
            "displayName": "Read all class assignments without grades",
            "id": "6e0a958b-b7fc-4348-b7c4-a6ab9fd3dd0e",
            "isEnabled": true,
            "origin": "Application",
            "value": "EduAssignments.ReadBasic.All"
        }
    ],
    "publishedPermissionScopes": [
        {
            "adminConsentDescription": "Allows the app to see your users' basic profile (e.g., name, picture, user name, email address)",
            "adminConsentDisplayName": "View users' basic profile",
            "id": "14dad69e-099b-42c9-810b-d002981feec1",
            "isEnabled": true,
            "type": "User",
            "userConsentDescription": "Allows the app to see your basic profile (e.g., name, picture, user name, email address)",
            "userConsentDisplayName": "View your basic profile",
            "value": "profile"
        }
    ]
}

例 3: 指定したサービス プリンシパルのカスタム セキュリティ属性の割り当てを取得する

次の例では、指定されたサービス プリンシパルのカスタム セキュリティ属性を取得します。

属性 #1

  • 属性セット: Engineering
  • 属性: Project
  • 属性データ型: 文字列のコレクション
  • 属性値: ["Baker","Cascade"]

属性 #2

  • 属性セット: Engineering
  • 属性: CostCenter
  • 属性データ型: 整数のコレクション
  • 属性値: [1001]

属性 #3

  • 属性セット: Engineering
  • 属性: Certification
  • 属性データ型: ブール値
  • 属性値: true

属性 #4

  • 属性セット: Marketing
  • 属性: Level
  • 属性データ型: 文字列
  • 属性値: "Public"

カスタム セキュリティ属性の割り当てを取得するには、呼び出し元のプリンシパルに属性割り当てリーダーまたは属性割り当て管理者の役割を割り当て、CustomSecAttributeAssignment.ReadWrite.All または CustomSecAttributeAssignment.ReadWrite.All のアクセス許可を付与する必要があります。

要求

GET https://graph.microsoft.com/beta/servicePrincipals/{id}?$select=customSecurityAttributes

応答

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(customSecurityAttributes)/$entity",
    "customSecurityAttributes": {
        "Engineering": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Project@odata.type": "#Collection(String)",
            "Project": [
                "Baker",
                "Cascade"
            ],
            "CostCenter@odata.type": "#Collection(Int32)",
            "CostCenter": [
                1001
            ],
            "Certification": true
        },
        "Marketing": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Level": "Public"
        }
    }
}

サービス プリンシパルにカスタム セキュリティ属性が割り当てられていない場合、または呼び出し元のプリンシパルにアクセス権がない場合、応答は次のようになります。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}