Freigeben über

Verarbeiten von Kontakten in Batches mithilfe von EWS in Exchange

  • Artikel

Erfahren Sie, wie Sie Batches von Kontakten in einem einzigen Aufruf erstellen, abrufen, aktualisieren und löschen, indem Sie die verwaltete EWS-API oder EWS in Exchange verwenden.

Sie können die verwaltete EWS-API oder EWS verwenden, um mit Batches von Kontakten zu arbeiten, um die Anzahl der Aufrufe zu reduzieren, die ein Client an einen Exchange-Server sendet. Wenn Sie die verwaltete EWS-API zum Erstellen, Abrufen, Aktualisieren und Löschen von Kontakten in Batches verwenden, verwenden Sie ExchangeService-Objektmethoden , während Sie bei der Arbeit mit einzelnen Kontakten Contact-Objektmethoden verwenden. Wenn Sie EWS verwenden, verwenden Sie dieselben Vorgänge, um sowohl mit einem einzelnen Kontakt als auch mit Batches von Kontakten zu arbeiten.

Tabelle 1. Verwaltete EWS-API-Methoden und EWS-Vorgänge zum Arbeiten mit Batches von Kontakten

Gewünschte Aktion Verwenden dieser verwalteten EWS-API-Methode Zu verwendender EWS-Vorgang
Erstellen von Kontakten in Batches
 ExchangeService.CreateItems
CreateItem
Abrufen von Kontakten in Batches
 ExchangeService.BindToItems oder ExchangeService.LoadPropertiesForItems
GetItem
Aktualisieren von Kontakten in Batches
 ExchangeService.UpdateItems
UpdateItem
Löschen von Kontakten in Batches
 ExchangeService.DeleteItems
DeleteItem

In diesem Artikel erfahren Sie, wie Sie grundlegende Aufgaben für Batches von Kontakten mithilfe der verwalteten EWS-API oder EWS ausführen.

Erstellen von Kontakten in Batches mithilfe der verwalteten EWS-API

Sie können Kontakte in Batches erstellen, indem Sie die CreateItems-Methode der verwalteten EWS-API verwenden, wie im folgenden Beispiel gezeigt. In diesem Beispiel werden drei Contact-Objekte lokal erstellt, jeder Kontakt einer Auflistung hinzugefügt und dann die CreateItems-Methode für die Auflistung von Kontakten aufgerufen.

public static Collection<ItemId> CreateContactsInBatch(ExchangeService service)
{
    // These are unsaved local instances of a Contact object.
    // Despite the required parameter of an ExchangeService object (service), no call
    // to an Exchange server is made when the objects are instantiated.
    // A call to the Exchange server is made when the service.CreateItems() method is called.
    Contact contact1 = new Contact(service);
    Contact contact2 = new Contact(service);
    Contact contact3 = new Contact(service);
    // Set the properties on the first contact.
    contact1.DisplayName = "Sadie Daniels";
    contact1.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("sadie@contoso.com");
    
    // Set the properties on the second contact.
    contact2.DisplayName = "Alfred Welker";
    contact2.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("alfred@contoso.com");
    // Set the properties on the third contact.
    contact3.DisplayName = "Hope Gross";
    contact3.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("hope@contoso.com");
    // Add the Contact objects to a collection.
    Collection<Contact> contactItems = new Collection<Contact>() { contact1, contact2, contact3 };
    // Create the batch of contacts on the server.
    // This method call results in an CreateItem call to EWS.
    ServiceResponseCollection<ServiceResponse> response = service.CreateItems(contactItems, WellKnownFolderName.Contacts, null, null);
    // Instantiate a collection of item IDs to populate from the values that are returned by the Exchange server.
    Collection<ItemId> itemIds = new Collection<ItemId>();
    // Collect the item IDs from the created contacts.
    foreach (Contact contact in contactItems)
    {
        try
        {
            itemIds.Add(contact.Id);
            Console.WriteLine("Contact '{0}' created successfully.", contact.DisplayName);
        }
        catch (Exception ex)
        {
            // Print out the exception and the last eight characters of the item ID.
            Console.WriteLine("Exception while creating contact {0}: {1}", contact.Id.ToString().Substring(144), ex.Message);
        }
    }
    // Determine whether the CreateItems method call completed successfully.
    if (response.OverallResult == ServiceResult.Success)
    {
            Console.WriteLine("All locally created contacts were successfully created in the Contacts folder.");
            Console.WriteLine("\r\n");
    }
   
    // If the method did not return success, print the result message for each contact.
    else
    {
        int counter = 1;
        foreach (ServiceResponse resp in response)
        {
            // Print out the result and the last eight characters of the item ID.
            Console.WriteLine("Result (contact {0}), id {1}: {2}", counter, itemIds[counter - 1].ToString().Substring(144), resp.Result);
            Console.WriteLine("Error Code: {0}", resp.ErrorCode);
            Console.WriteLine("ErrorMessage: {0}\r\n", resp.ErrorMessage);
            Console.WriteLine("\r\n");
            counter++;
        }
    }
    return itemIds;
}

Erstellen von Kontakten in Batches mithilfe von EWS

Sie können Kontakte in Batches erstellen, indem Sie den EWS-Vorgang CreateItem verwenden, wie im folgenden Codebeispiel gezeigt. Dies ist auch die XML-Anforderung, die die verwaltete EWS-API sendet, wenn Sie die verwaltete EWS-API verwenden, um Kontakte in Batches zu erstellen.

<?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" 
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header>
      <t:RequestServerVersion Version="Exchange2007_SP1" />
    </soap:Header>
    <soap:Body>
      <m:CreateItem>
        <m:SavedItemFolderId>
          <t:DistinguishedFolderId Id="contacts" />
        </m:SavedItemFolderId>
        <m:Items>
          <t:Contact>
            <t:DisplayName>Sadie Daniels</t:DisplayName>
            <t:EmailAddresses>
              <t:Entry Key="EmailAddress1">sadie@contoso.com</t:Entry>
            </t:EmailAddresses>
          </t:Contact>
          <t:Contact>
            <t:DisplayName>Alfred Welker</t:DisplayName>
            <t:EmailAddresses>
              <t:Entry Key="EmailAddress1">alfred@contoso.com</t:Entry>
            </t:EmailAddresses>
          </t:Contact>
          <t:Contact>
            <t:DisplayName>Hope Gross</t:DisplayName>
            <t:EmailAddresses>
              <t:Entry Key="EmailAddress1">hope@contoso.com</t:Entry>
            </t:EmailAddresses>
          </t:Contact>
        </m:Items>
      </m:CreateItem>
    </soap:Body>
  </soap:Envelope>

Der Server antwortet auf die CreateItem-Anforderung mit einer CreateItemResponse-Nachricht , die den ResponseCode-WertNoError für jeden der neuen Kontakte enthält, was angibt, dass jeder Kontakt erfolgreich erstellt und gespeichert wurde.

Abrufen von Kontakten in Batches mithilfe der verwalteten EWS-API

Sie können Kontakte in Batches abrufen, indem Sie die BindToItems-Methode der verwalteten EWS-API verwenden, wie im folgenden Beispiel gezeigt. In diesem Beispiel wird davon ausgegangen, dass service ein gültiges ExchangeService-Objekt ist und der Benutzer bei einem Exchange-Server authentifiziert wurde.

public static Collection<Contact> BatchGetContactItems(ExchangeService service, Collection<ItemId> itemIds)
        {
            // Create a property set that limits the properties returned by the Bind method to only those that are required.
            PropertySet propSet = new PropertySet(BasePropertySet.IdOnly, ContactSchema.DisplayName);
            // Get the items from the server.
            // This method call results in a GetItem call to EWS.
            ServiceResponseCollection<GetItemResponse> response = service.BindToItems(itemIds, propSet);
            // Instantiate a collection of Contact objects to populate from the values that are returned by the Exchange server.
            Collection<Contact> contactItems = new Collection<Contact>();
            foreach (GetItemResponse getItemResponse in response)
            {
                try
                {
                    Item item = getItemResponse.Item;
                    Contact contact = (Contact)item;
                    contactItems.Add(contact);
                    // Print out confirmation and the last eight characters of the item ID.
                    Console.WriteLine("Found item {0}.", contact.Id.ToString().Substring(144));
                }
                catch (Exception ex)
                {
                    Console.WriteLine("Exception while getting a contact: {0}", ex.Message);
                }
            }
            // Check for success of the BindToItems method call.
            if (response.OverallResult == ServiceResult.Success)
            {
                Console.WriteLine("All contacts retrieved successfully.");
                Console.WriteLine("\r\n");
            }
            return contactItems;
        }

Abrufen von Kontakten in Batches mithilfe von EWS

Sie können Kontakte in Batches abrufen, indem Sie den EWS-Vorgang GetItem und den Code im folgenden Beispiel verwenden. Dies ist auch die XML-Anforderung, die die verwaltete EWS-API sendet, wenn Sie die verwaltete EWS-API verwenden, um Kontakte in Batches abzurufen. Das ItemId-Attribut wurde aus Gründen der Lesbarkeit gekürzt.

<?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" 
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header>
      <t:RequestServerVersion Version="Exchange2007_SP1" />
    </soap:Header>
    <soap:Body>
      <m:GetItem>
        <m:ItemShape>
          <t:BaseShape>IdOnly</t:BaseShape>
          <t:AdditionalProperties>
            <t:FieldURI FieldURI="contacts:DisplayName" />
          </t:AdditionalProperties>
        </m:ItemShape>
        <m:ItemIds>
          <t:ItemId Id="ceJwVAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yS" />
          <t:ItemId Id="ceJwWAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yT" />
          <t:ItemId Id="ceJwXAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yU" />
        </m:ItemIds>
      </m:GetItem>
    </soap:Body>
  </soap:Envelope>

Der Server antwortet auf die GetItem-Anforderung mit einer GetItemResponse-Nachricht , die die ID und den Anzeigenamen für jeden der angeforderten Kontakte enthält.

Aktualisieren von Kontakten in Batches mithilfe der verwalteten EWS-API

Sie können Kontakte in Batches mithilfe der UpdateItems-Methode der verwalteten EWS-API aktualisieren, wie im folgenden Beispiel gezeigt. Im vorherigen Beispiel wird der Kontakt erstellt, aber nicht angegeben, für wen er arbeitet. Sie können den Code in diesem Beispiel verwenden, um alle Ihre Kontakte gleichzeitig so zu aktualisieren, dass sie ihren Firmennamen enthalten.

In diesem Beispiel wird davon ausgegangen, dass service ein gültiges ExchangeService-Objekt ist und der Benutzer bei einem Exchange-Server authentifiziert wurde.

public static Collection<Contact> BatchUpdateContactItems(ExchangeService service, Collection<Contact> contactItems)
        {
            // Update the company name of each contact locally.
            foreach (Contact contact in contactItems)
            {
                // Update the company name of the contact.
                contact.CompanyName = "Contoso";
                // Print out confirmation with the last eight characters of the item ID and the contact company name.
                Console.WriteLine("Updated local contact {0} with the company name '{1}'.", contact.Id.ToString().Substring(144), contact.CompanyName);
            }
            
            // Send the item updates to the server.
            // This method call results in an UpdateItem call to EWS.
            ServiceResponseCollection<UpdateItemResponse> response = service.UpdateItems(contactItems, WellKnownFolderName.Contacts, ConflictResolutionMode.AutoResolve, null, null);
            // Verify the success of the UpdateItems method call.
            if (response.OverallResult == ServiceResult.Success)
            {
                Console.WriteLine("All contacts updated successfully.\r\n");
            }
            // If the method did not return success, print the result message for each contact.
            else
            {
                Console.WriteLine("All contacts were not successfully saved on the server.\r\n");
                int counter = 1;
                foreach (ServiceResponse resp in response)
                {
                    Console.WriteLine("Result for (contact {0}): {1}", counter, resp.Result);
                    Console.WriteLine("Error Code: {0}", resp.ErrorCode);
                    Console.WriteLine("ErrorMessage: {0}\r\n", resp.ErrorMessage);
                    counter++;
                }
            }
            return contactItems;
        }

Aktualisieren von Kontakten in Batches mithilfe von EWS

Sie können Kontakte in Batches mithilfe des EWS-Vorgangs GetItem aktualisieren, wie im folgenden Codebeispiel gezeigt. Dies ist auch die XML-Anforderung, die die verwaltete EWS-API sendet, wenn Sie die verwaltete EWS-API verwenden, um Kontakte in Batches zu aktualisieren. Das ItemId-Attribut wurde aus Gründen der Lesbarkeit gekürzt.

<?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" 
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header>
      <t:RequestServerVersion Version="Exchange2007_SP1" />
    </soap:Header>
    <soap:Body>
      <m:UpdateItem ConflictResolution="AutoResolve">
        <m:SavedItemFolderId>
          <t:DistinguishedFolderId Id="contacts" />
        </m:SavedItemFolderId>
        <m:ItemChanges>
          <t:ItemChange>
            <t:ItemId Id="ceJwVAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yS" />
            <t:Updates>
              <t:SetItemField>
                <t:FieldURI FieldURI="contacts:CompanyName" />
                <t:Contact>
                  <t:CompanyName>Contoso</t:CompanyName>
                </t:Contact>
              </t:SetItemField>
            </t:Updates>
          </t:ItemChange>
          <t:ItemChange>
            <t:ItemId Id="ceJwWAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yT" />
            <t:Updates>
              <t:SetItemField>
                <t:FieldURI FieldURI="contacts:CompanyName" />
                <t:Contact>
                  <t:CompanyName>Contoso</t:CompanyName>
                </t:Contact>
              </t:SetItemField>
            </t:Updates>
          </t:ItemChange>
          <t:ItemChange>
            <t:ItemId Id="ceJwXAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yU" />
            <t:Updates>
              <t:SetItemField>
                <t:FieldURI FieldURI="contacts:CompanyName" />
                <t:Contact>
                  <t:CompanyName>Contoso</t:CompanyName>
                </t:Contact>
              </t:SetItemField>
            </t:Updates>
          </t:ItemChange>
        </m:ItemChanges>
      </m:UpdateItem>
    </soap:Body>
  </soap:Envelope>

Der Server antwortet auf die UpdateItem-Anforderung mit einer UpdateItemResponse-Nachricht , die den ResponseCode-WertNoError enthält, der angibt, dass jedes der Updates erfolgreich auf dem Server gespeichert wurde. Alle Konflikte werden im ConflictResult-Element gemeldet.

Löschen von Kontakten in Batches mithilfe der verwalteten EWS-API

Sie können Kontakte in Batches löschen, indem Sie die DeleteItems EWS Managed API-Methode verwenden, wie im folgenden Beispiel gezeigt. In diesem Beispiel wird davon ausgegangen, dass service ein gültiges ExchangeService-Objekt ist und der Benutzer bei einem Exchange-Server authentifiziert wurde.

public static void BatchDeleteContactItems(ExchangeService service, Collection<ItemId> itemIds)
        {
            // Delete the batch of contact objects.
            // This method call results in an DeleteItem call to EWS.
            ServiceResponseCollection<ServiceResponse> response = service.DeleteItems(itemIds, DeleteMode.SoftDelete, null, AffectedTaskOccurrence.AllOccurrences);
            // Check for success of the DeleteItems method call.
            // DeleteItems returns success even if it does not find all the item IDs.
            if (response.OverallResult == ServiceResult.Success)
            {
                Console.WriteLine("Contacts deleted successfully.\r\n");
            }
            // If the method did not return success, print a message.
            else
            {
                Console.WriteLine("Not all contacts deleted successfully.\r\n");
            }
        }

Löschen von Kontakten in Batches mithilfe von EWS

Sie können Kontakte in Batches mithilfe des EWS-Vorgangs DeleteItem löschen, wie im folgenden Codebeispiel gezeigt. Dies ist auch die XML-Anforderung, die die verwaltete EWS-API sendet, wenn Sie die verwaltete EWS-API zum Löschen von Kontakten in Batches verwenden. Das ItemId-Attribut wurde aus Gründen der Lesbarkeit gekürzt.

<?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" 
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header>
      <t:RequestServerVersion Version="Exchange2007_SP1" />
    </soap:Header>
    <soap:Body>
      <m:DeleteItem DeleteType="SoftDelete" AffectedTaskOccurrences="AllOccurrences">
        <m:ItemIds>
          <t:ItemId Id="ceJwYAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yY" />
          <t:ItemId Id="ceJwZAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yZ" />
          <t:ItemId Id="ceJwaAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51ya" />
        </m:ItemIds>
      </m:DeleteItem>
    </soap:Body>
  </soap:Envelope>

Der Server antwortet auf die DeleteItem-Anforderung mit einer DeleteItemResponse-Nachricht , die den ResponseCode-WertNoError für jedes entfernte Element enthält. Beachten Sie, dass der Vorgang auch einen Erfolg zurückgibt, wenn die Element-ID nicht gefunden werden konnte.

Überprüfen, ob ein Batchprozess erfolgreich abgeschlossen wurde

Wenn ein oder mehrere Kontakte in einer Batchanforderung nicht wie angefordert verarbeitet werden können, wird für jeden Kontakt, bei dem ein Fehler aufgetreten ist, ein Fehler zurückgegeben, und die restlichen Kontakte im Batch werden wie erwartet verarbeitet. Fehler bei der Batchverarbeitung können auftreten, wenn das Element gelöscht wurde und daher nicht abgerufen oder aktualisiert werden kann, oder wenn das Element in einen anderen Ordner verschoben wurde und daher über eine neue Element-ID verfügt und nicht mit der gesendeten Element-ID geändert werden kann. Die Informationen in diesem Abschnitt zeigen, wie Fehlerdetails zu Fehlern bei der Batchverarbeitung von Kontakten abgerufen werden.

Um den Erfolg eines Batchprozesses mithilfe der verwalteten EWS-API zu überprüfen, können Sie überprüfen, ob die OverallResult-Eigenschaft der ServiceResponseCollectiongleich ServiceResult.Success ist. Wenn ja, wurden alle Kontakte erfolgreich verarbeitet. Wenn das OverallResult ungleich ServiceResult.Success ist, wurde mindestens einer der Kontakte nicht erfolgreich verarbeitet. Jedes der in serviceResponseCollection zurückgegebenen Objekte enthält die folgenden Eigenschaften:

Diese Eigenschaften enthalten Informationen darüber, warum die Kontakte nicht wie angefordert verarbeitet werden konnten. In den Beispielen in diesem Artikel werden die Beispiele Result, ErrorCode und ErrorMessage für jeden fehlerhaften Kontakt ausgegeben. Sie können diese Ergebnisse verwenden, um das Problem zu untersuchen.

Überprüfen Sie für EWS das ResponseClass-Attribut für jedes verarbeitete Element, um den Erfolg eines Batchprozesses zu überprüfen. Es folgt die grundlegende Struktur von ResponseMessageType, dem Basistyp, von dem alle Antwortnachrichten abgeleitet werden.

<ResponseMessage ResponseClass="Success | Warning | Error">
            <MessageText/>
            <ResponseCode/>
            <DescriptiveLinkKey/>
            <MessageXml/>
</ResponseMessage>

Das ResponseClass-Attribut ist auf Success festgelegt, wenn der Kontakt erfolgreich verarbeitet wurde, oder Auf Fehler , wenn der Kontakt nicht erfolgreich verarbeitet wurde. Bei Kontakten wird während der Batchverarbeitung keine Warnung angezeigt. Wenn ResponseClassauf Success festgelegt ist, wird auch das darauf folgende ResponseCode-Element immer auf NoError festgelegt. Wenn ResponseClassauf Error festgelegt ist, müssen Sie die Werte der MessageText-, ResponseCode- und MessageXml-Elemente überprüfen, um zu ermitteln, was das Problem verursacht hat. DescriptiveLinkKey wird derzeit nicht verwendet.

Siehe auch