Operação GetUserAvailabilityGetUserAvailability operation

Encontre informações sobre a operação do EWS do GetUserAvailability .Find information about the GetUserAvailability EWS operation.

A operação GetUserAvailability fornece informações detalhadas sobre a disponibilidade de um conjunto de usuários, salas e recursos dentro de um período de tempo especificado.The GetUserAvailability operation provides detailed information about the availability of a set of users, rooms, and resources within a specified time period.

Usando a operação GetUserAvailabilityUsing the GetUserAvailability operation

A operação GetUserAvailability fornece as informações de disponibilidade do usuário atual em um nível especificado de detalhes.The GetUserAvailability operation provides current user availability information at a specified level of detail. Aplicativos cliente como Outlook, Outlook Web Access, Outlook Mobile Access e outros usam endereços SMTP para identificar as informações de usuário solicitadas.Client applications such as Outlook, Outlook Web Access, Outlook Mobile Access, and others use SMTP addresses to identify the requested user information.

O serviço de disponibilidade expande as listas de distribuição para recuperar o status de disponibilidade de cada membro da lista, desde que o número de caixas de correio na lista de distribuição seja menor que 100, que é o número máximo de identidades que a operação GetUserAvailability pode solicitar.The Availability service expands distribution lists to retrieve the free/busy status for each member of the list, as long as the number of mailboxes in the distribution list is less than 100, which is the maximum number of identities that the GetUserAvailability operation can request. Os status de disponibilidade dos membros da lista de distribuição são mesclados em um único status de disponibilidade para toda a lista de distribuição.The free/busy statuses of the members of the distribution list are merged into a single free/busy status for the whole distribution list.

Solicitações de aplicativo cliente especificam o período de tempo da consulta de disponibilidade.Client application requests specify the time period of the availability query. O período de tempo padrão para as informações solicitadas é de 42 dias.The default time period for the requested information is 42 days. Se o calendário do usuário contiver compromissos ou reuniões que estejam dentro e fora do período de tempo definido para a consulta, o compromisso será retornado.If the user's calendar contains appointments or meetings that are both within and outside the defined time period for the query, the appointment is returned.

O compromisso e os horários de reunião retornados estão no mesmo fuso horário que o aplicativo cliente que está solicitando a reunião.The appointment and meeting times that are returned are in the same time zone as the client application that is requesting the meeting.

O serviço de disponibilidade processa a solicitação para cada cliente.The Availability service processes the request for each client. O serviço expande todos os compromissos recorrentes e retorna o número máximo de detalhes do calendário que o cliente solicitante tem permissão para receber.The service expands all the recurring appointments and returns the maximum number of calendar details that the requesting client has permission to receive.

Observação

Se a caixa de correio de destino estiver indisponível ou não puder ser encontrada, uma exceção MailRecipientNotFoundException será lançada.If the target mailbox is unavailable or cannot be found, a MailRecipientNotFoundException exception is thrown. O cliente recebe uma mensagem de erro que indica que o destinatário do email não é encontrado no serviço de diretório do Active Directory ou no AD DS (serviços de domínio Active Directory).The client receives an error message that states that the mail recipient is not found in the Active Directory directory service or Active Directory Domain Services (AD DS).

Cabeçalhos SOAP de operação GetUserAvailabilityGetUserAvailability operation SOAP headers

A operação GetUserAvailability pode usar os cabeçalhos SOAP listados na tabela a seguir.The GetUserAvailability operation can use the SOAP headers that are listed in the following table.

HeaderHeader ElementoElement DescriçãoDescription
RepresentaçãoImpersonation
ExchangeImpersonationExchangeImpersonation
Identifica o usuário que o cliente está representando.Identifies the user whom the client is impersonating. Este cabeçalho é aplicável a uma solicitação.This header is applicable to a request.
RequestVersionRequestVersion
RequestServerVersionRequestServerVersion
Identifica a versão do esquema para a solicitação de operação.Identifies the schema version for the operation request. Este cabeçalho é aplicável a uma solicitação.This header is applicable to a request.
ServerVersionServerVersion
ServerVersionInfoServerVersionInfo
Identifica a versão do servidor que respondeu à solicitação.Identifies the version of the server that responded to the request. Este cabeçalho é aplicável a uma resposta.This header is applicable to a response.
TimeZoneContextTimeZoneContext
TimeZoneContextTimeZoneContext
Especifica um cabeçalho SOAP que identifica o fuso horário a ser usado para todas as respostas do servidor.Specifies a SOAP header that identifies the time zone to be used for all responses from the server. Todas as horas retornadas do servidor serão convertidas no fuso horário especificado.All times that are returned from the server will be converted to the specified time zone. Este cabeçalho é aplicável a uma resposta.This header is applicable to a response.

Exemplo de solicitação GetUserAvailability: obter informações de disponibilidadeGetUserAvailability request example: Get availability information

O exemplo a seguir de uma solicitação de operação GetUserAvailability mostra como obter informações detalhadas de disponibilidade de dois usuários no fuso horário do Pacífico.The following example of a GetUserAvailability operation request shows how to get detailed availability information for two users in the Pacific Time time zone.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <GetUserAvailabilityRequest xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
                xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <t:TimeZone xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
        <Bias>480</Bias>
        <StandardTime>
          <Bias>0</Bias>
          <Time>02:00:00</Time>
          <DayOrder>5</DayOrder>
          <Month>10</Month>
          <DayOfWeek>Sunday</DayOfWeek>
        </StandardTime>
        <DaylightTime>
          <Bias>-60</Bias>
          <Time>02:00:00</Time>
          <DayOrder>1</DayOrder>
          <Month>4</Month>
          <DayOfWeek>Sunday</DayOfWeek>
        </DaylightTime>
      </t:TimeZone>
      <MailboxDataArray>
        <t:MailboxData>
          <t:Email>
            <t:Address>user1@example.com</t:Address>
          </t:Email>
          <t:AttendeeType>Required</t:AttendeeType>
          <t:ExcludeConflicts>false</t:ExcludeConflicts>
        </t:MailboxData>
        <t:MailboxData>
          <t:Email>
            <t:Address>user2@example.com</t:Address>
          </t:Email>
          <t:AttendeeType>Required</t:AttendeeType>
          <t:ExcludeConflicts>false</t:ExcludeConflicts>
        </t:MailboxData>
      </MailboxDataArray>
      <t:FreeBusyViewOptions>
        <t:TimeWindow>
          <t:StartTime>2006-10-16T00:00:00</t:StartTime>
          <t:EndTime>2006-10-16T23:59:59</t:EndTime>
        </t:TimeWindow>
        <t:MergedFreeBusyIntervalInMinutes>60</t:MergedFreeBusyIntervalInMinutes>
        <t:RequestedView>DetailedMerged</t:RequestedView>
      </t:FreeBusyViewOptions>
    </GetUserAvailabilityRequest>
  </soap:Body>
</soap:Envelope>

Para obter mais informações sobre como recuperar reuniões sugeridas usando o elemento SuggestionsViewOptions , consulte o esquema no diretório virtual do EWS.For more information about retrieving suggested meetings by using the SuggestionsViewOptions element, see the schema in the EWS virtual directory.

O corpo SOAP de solicitação contém os seguintes elementos:The request SOAP body contains the following elements:

Resposta de operação GetUserAvailability bem-sucedidaSuccessful GetUserAvailability operation response

O exemplo a seguir mostra uma resposta bem-sucedida à solicitação de operação GetUserAvailability .The following example shows a successful response to the GetUserAvailability operation request.

Observação

Os identificadores de eventos de calendário foram reduzidos para preservar a legibilidade.The calendar event identifiers have been shortened to preserve readability.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="665" MinorBuildNumber="7" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <GetUserAvailabilityResponse xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <FreeBusyResponseArray>
        <FreeBusyResponse>
          <ResponseMessage ResponseClass="Success">
            <ResponseCode>NoError</ResponseCode>
          </ResponseMessage>
          <FreeBusyView>
            <FreeBusyViewType xmlns="https://schemas.microsoft.com/exchange/services/2006/types">DetailedMerged</FreeBusyViewType>
            <MergedFreeBusy xmlns="https://schemas.microsoft.com/exchange/services/2006/types">000002220220000000000000</MergedFreeBusy>
            <CalendarEventArray xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
              <CalendarEvent>
                <StartTime>2006-10-16T06:00:00-07:00</StartTime>
                <EndTime>2006-10-16T06:30:00-07:00</EndTime>
                <BusyType>Busy</BusyType>
                <CalendarEventDetails>
                  <ID>14B6414B0</ID>
                  <Subject>Meet with Contoso Account Executives</Subject>
                  <Location />
                  <IsMeeting>false</IsMeeting>
                  <IsRecurring>false</IsRecurring>
                  <IsException>false</IsException>
                  <IsReminderSet>false</IsReminderSet>
                  <IsPrivate>false</IsPrivate>
                </CalendarEventDetails>
              </CalendarEvent>
              <CalendarEvent>
                <StartTime>2006-10-16T07:00:00-07:00</StartTime>
                <EndTime>2006-10-16T08:00:00-07:00</EndTime>
                <BusyType>Busy</BusyType>
                <CalendarEventDetails>
                  <ID>E14B6414B0B</ID>
                  <Subject>Pick up my groceries</Subject>
                  <Location />
                  <IsMeeting>false</IsMeeting>
                  <IsRecurring>false</IsRecurring>
                  <IsException>false</IsException>
                  <IsReminderSet>false</IsReminderSet>
                  <IsPrivate>false</IsPrivate>
                </CalendarEventDetails>
              </CalendarEvent>
              <CalendarEvent>
                <StartTime>2006-10-16T09:40:00-07:00</StartTime>
                <EndTime>2006-10-16T10:10:00-07:00</EndTime>
                <BusyType>Busy</BusyType>
                <CalendarEventDetails>
                  <ID>14B6414B0B1</ID>
                  <Subject>Meet with doctor</Subject>
                  <Location>Kirkland</Location>
                  <IsMeeting>false</IsMeeting>
                  <IsRecurring>false</IsRecurring>
                  <IsException>false</IsException>
                  <IsReminderSet>false</IsReminderSet>
                  <IsPrivate>false</IsPrivate>
                </CalendarEventDetails>
              </CalendarEvent>
            </CalendarEventArray>
            <WorkingHours xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
              <TimeZone>
                <Bias>480</Bias>
                <StandardTime>
                  <Bias>0</Bias>
                  <Time>02:00:00</Time>
                  <DayOrder>5</DayOrder>
                  <Month>10</Month>
                  <DayOfWeek>Sunday</DayOfWeek>
                </StandardTime>
                <DaylightTime>
                  <Bias>-60</Bias>
                  <Time>02:00:00</Time>
                  <DayOrder>1</DayOrder>
                  <Month>4</Month>
                  <DayOfWeek>Sunday</DayOfWeek>
                </DaylightTime>
              </TimeZone>
              <WorkingPeriodArray>
                <WorkingPeriod>
                  <DayOfWeek>Monday Tuesday Wednesday Thursday Friday</DayOfWeek>
                  <StartTimeInMinutes>480</StartTimeInMinutes>
                  <EndTimeInMinutes>1020</EndTimeInMinutes>
                </WorkingPeriod>
              </WorkingPeriodArray>
            </WorkingHours>
          </FreeBusyView>
        </FreeBusyResponse>
        <FreeBusyResponse>
          <ResponseMessage ResponseClass="Success">
            <ResponseCode>NoError</ResponseCode>
          </ResponseMessage>
          <FreeBusyView>
            <FreeBusyViewType xmlns="https://schemas.microsoft.com/exchange/services/2006/types">FreeBusyMerged</FreeBusyViewType>
            <MergedFreeBusy xmlns="https://schemas.microsoft.com/exchange/services/2006/types">000000001100000000000000</MergedFreeBusy>
            <CalendarEventArray xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
              <CalendarEvent>
                <StartTime>2006-10-16T09:00:00-07:00</StartTime>
                <EndTime>2006-10-16T10:00:00-07:00</EndTime>
                <BusyType>Tentative</BusyType>
              </CalendarEvent>
            </CalendarEventArray>
            <WorkingHours xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
              <TimeZone>
                <Bias>480</Bias>
                <StandardTime>
                  <Bias>0</Bias>
                  <Time>02:00:00</Time>
                  <DayOrder>5</DayOrder>
                  <Month>10</Month>
                  <DayOfWeek>Sunday</DayOfWeek>
                </StandardTime>
                <DaylightTime>
                  <Bias>-60</Bias>
                  <Time>02:00:00</Time>
                  <DayOrder>1</DayOrder>
                  <Month>4</Month>
                  <DayOfWeek>Sunday</DayOfWeek>
                </DaylightTime>
              </TimeZone>
              <WorkingPeriodArray>
                <WorkingPeriod>
                  <DayOfWeek>Monday Tuesday Wednesday Thursday Friday</DayOfWeek>
                  <StartTimeInMinutes>480</StartTimeInMinutes>
                  <EndTimeInMinutes>1020</EndTimeInMinutes>
                </WorkingPeriod>
              </WorkingPeriodArray>
            </WorkingHours>
          </FreeBusyView>
        </FreeBusyResponse>
      </FreeBusyResponseArray>
    </GetUserAvailabilityResponse>
  </soap:Body>
</soap:Envelope>

As informações de disponibilidade para cada usuário são exibidas em um elemento FreeBusyResponse exclusivo.The availability information for each user appears in a unique FreeBusyResponse element. A ordem dos usuários na solicitação de operação GetUserAvailability determina a ordem dos dados de disponibilidade para cada usuário na resposta.The order of users in the GetUserAvailability operation request determines the order of availability data for each user in the response.

Um erro será retornado ao cliente se o número de compromissos no período de tempo definido na consulta for maior do que o número máximo especificado pelo administrador.An error will be returned to the client if the number of appointments in the time period that is defined in the query is greater than the administrator-specified maximum number. O número máximo padrão de compromissos é de 10.000 instâncias únicas e itens de recorrência expandidos.The default maximum number of appointments is 10,000 single instances and expanded recurrence items. Essa propriedade pode ser configurada somente por um administrador.This property can be configured only by an administrator.

Os seguintes elementos são usados na resposta:The following elements are used in the response:

Confira tambémSee also