次の方法で共有

servicePrincipal を取得する

  • [アーティクル]

名前空間: microsoft.graph

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 /applicationsを呼び出してGET /servicePrincipalsして、テナント内のすべてのアプリケーションとサービス プリンシパルを一覧表示できます。 このアクセス範囲は、アクセス許可に対して許可されています。
  • customSecurityAttributes プロパティを読み取る方法:
    • 委任されたシナリオでは、管理者に 属性割り当て管理者ロールを割り当て 、アプリに CustomSecAttributeAssignment.Read.All 委任されたアクセス許可が付与されている必要があります。
    • Microsoft Graph のアクセス許可を使用するアプリのみのシナリオでは、アプリに CustomSecAttributeAssignment.Reade.All アプリケーションのアクセス許可を付与する必要があります。

HTTP 要求

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

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

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

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

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: サービス プリンシパルを ID で取得する

要求

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

GET https://graph.microsoft.com/v1.0/servicePrincipals/00063ffc-54e9-405d-b8f3-56124728e051

応答

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

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

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

{
  "accountEnabled": true,
  "addIns": [],
  "alternativeNames": ["http://contoso/a7770d29-4321-41a6-b863-ca11d6639448"],
  "appDisplayName": "My app",
  "appId": "appId-value",
  "appOwnerOrganizationId": "65415bb1-9267-4313-bbf5-ae259732ee12",
  "appRoleAssignmentRequired":true,
  "appRoles": [],
  "disabledByMicrosoftStatus": null,
  "displayName": "My app instance in tenant",
  "endpoints": [],
  "homepage": null,
  "id": "00af5dfb-85da-4b41-a677-0c6b86dd34f8",
  "verifiedPublisher": {
            "displayName": "publisher_contoso",
            "verifiedPublisherId": "9999999",
             "addedDateTime": "2021-04-24T17:49:44Z"
    },
  "info": {
    "termsOfServiceUrl": null,
    "supportUrl": null,
    "privacyStatementUrl": null,
    "marketingUrl": null,
    "logoUrl": null
  },
  "keyCredentials": [],
  "logoutUrl": null,
  "oauth2PermissionScopes": [],
  "passwordCredentials": [],
  "publisherName": null,
  "replyUrls": [],
  "resourceSpecificApplicationPermissions": [],
  "servicePrincipalNames": [],
  "servicePrincipalType": null,
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "tags": [],
  "tokenEncryptionKeyId": null
}

例 2: サービス プリンシパルの特定のプロパティを取得する

要求

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

GET https://graph.microsoft.com/v1.0/servicePrincipals/7408235b-7540-4850-82fe-a5f15ed019e2?$select=id,appId,displayName,appRoles,oauth2PermissionScopes,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"
        }
    ],
    "oauth2PermissionScopes": [
        {
            "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/v1.0/servicePrincipals/{id}?$select=customSecurityAttributes

応答

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$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/v1.0/$metadata#servicePrincipals(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}