Listar contatos

Namespace: microsoft.graph

Obter contactos na caixa de correio do utilizador.

Há duas situações em que um aplicativo pode obter contatos na pasta de contatos de outro usuário:

• Se o aplicativo tiver permissões de aplicativo ou
• Se o aplicativo tiver as permissões delegadas apropriadas de um usuário, e outro usuário tiver compartilhado uma pasta de contatos com esse usuário, ou tiver concedido acesso delegado a esse usuário. Confira detalhes e um exemplo.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Solicitação HTTP

Para obter todos os contatos na pasta de Contatos padrão do usuário:

GET /me/contacts
GET /users/{id | userPrincipalName}/contacts

Para obter os contatos em uma pasta específica na caixa de correio do usuário:

GET /me/contactfolders/{Id}/contacts
GET /users/{id | userPrincipalName}/contactfolders/{id}/contacts

GET /me/contactFolders/{id}/childFolders/{id}/.../contacts
GET /users/{id | userPrincipalName}/contactFolders/{id}/childFolders/{id}/contacts

Parâmetros de consulta opcionais

Você pode usar o $filterparâmetro de consulta para filtrar contatos com base em seus endereços de email:

GET https://graph.microsoft.com/beta/me/contacts?$filter=emailAddresses/any(a:a/address eq 'garth@contoso.com')

Observe que você pode usar $filter, any, e o eq operador apenas na subpropriedade de endereço das instâncias em uma coleção emailAddresses. Ou seja, você não pode filtrar o nome ou qualquer outra subpropriedade de uma instância de emailAddresses, nem pode aplicar qualquer outro operador ou função com filter, como ne, le e startswith().

Para obter informações gerais sobre o $filterparâmetro de consulta, acesse Parâmetros de consulta OData.

Cabeçalhos de solicitação

Corpo da solicitação

Não forneça um corpo de solicitação para esse método.

Resposta

Se for bem-sucedido, este método devolve um 200 OK código de resposta e uma coleção de objetos de contacto no corpo da resposta.

Exemplo

Solicitação

O exemplo seguinte obtém as propriedades displayName e emailAddresses dos contactos do utilizador com sessão iniciada.

GET https://graph.microsoft.com/beta/me/contacts?$select=displayName,emailAddresses

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Contacts.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","emailAddresses" };
});

// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
	  //other-imports
)

requestParameters := &graphusers.ItemContactsRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","emailAddresses"},
}
configuration := &graphusers.ItemContactsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
contacts, err := graphClient.Me().Contacts().Get(context.Background(), configuration)

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ContactCollectionResponse result = graphClient.me().contacts().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "emailAddresses"};
});

const options = {
	authProvider,
};

const client = Client.init(options);

let contacts = await client.api('/me/contacts')
	.version('beta')
	.select('displayName,emailAddresses')
	.get();

<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\Contacts\ContactsRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new ContactsRequestBuilderGetRequestConfiguration();
$queryParameters = ContactsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","emailAddresses"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->contacts()->get($requestConfiguration)->wait();

Import-Module Microsoft.Graph.Beta.PersonalContacts

# A UPN can also be used as -UserId.
Get-MgBetaUserContact -UserId $userId -Property "displayName,emailAddresses" 

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.item.contacts.contacts_request_builder import ContactsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ContactsRequestBuilder.ContactsRequestBuilderGetQueryParameters(
		select = ["displayName","emailAddresses"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.contacts.get(request_configuration = request_configuration)

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{
    "@odata.context":"https://graph.microsoft.com/beta/$metadata#users('c3e1fcd2-db78-42a8-aec5-1f2cd59abb5c')/contacts(displayName,emailAddresses)",
    "value":[
        {
            "@odata.etag":"W/\"EQAAABYAAACv7At+UNVFRLhGciJGF6v5AAAve7f6\"",
            "id":"AAMkADh6v5AAAvgTCFAAA=",
            "displayName":"Elvis Blank",
            "emailAddresses":[
                {
                    "type":"personal",
                    "name":"Elvis Blank",
                    "address":"elvisb@contoso.com"
                },
                {
                    "type":"other",
                    "otherLabel":"Volunteer work",
                    "name":"Elvis Blank",
                    "address":"elvisb@contoso.com"
                }
            ]
        },
        {
            "@odata.etag":"W/\"EQAAABYAAACv7At+UNVFRLhGciJGF6v5AAAve7fn\"",
            "id":"AAMkADh6v5AAAvgTCEAAA=",
            "displayName":"Pavel Bansky",
            "emailAddresses":[
                {
                    "type":"personal",
                    "name":"Pavel Bansky",
                    "address":"pavelb@contoso.com"
                },
                {
                    "type":"other",
                    "otherLabel":"Volunteer work",
                    "name":"Pavel Bansky",
                    "address":"pavelb@contoso.com"
                }
            ]
        }
    ]
}