İletişim SDK'larında dize tanımlayıcıları için kullanım örnekleri

Bu makalede, Azure İletişim Hizmetleri SDK'larda CommunicationIdentifier türünün temsil türü olarak bir dize (Ham Kimlik) seçmek için kullanım örnekleri sağlanır. Bu kılavuzu takip etmek, CommunicationIdentifier türetilmiş türleri yerine Bir Ham Kimlik seçmek isteyebileceğiniz bazı kullanım örneklerini anlamanıza yardımcı olur.

Tanımlayıcı seçmek için kullanım örnekleri

İletişim senaryolarını uygularken sık kullanılan bir görev, konuşma katılımcılarını belirlemektir. İletişim Hizmetleri SDK'larını kullanırken, CommunicationIdentifier bu katılımcıları benzersiz olarak tanımlama özelliği sağlar.

CommunicationIdentifier aşağıdaki avantajlara sahiptir:

• IDE'lerde iyi bir otomatik tamamlama sağlar.
• Farklı uygulama akışlarını ele almak için türe göre anahtar servis talebi kullanılmasına izin verir.
• İletişimin belirli türlerde kısıtlanmasına izin verir.
• Tanımlayıcı ayrıntılarına erişime izin verin ve iletişim katılımcılarına zengin bir deneyim sağlamak üzere diğer API'leri (Microsoft Graph API'si gibi) çağırmak için bunları kullanın.

Bunun üzerine, CommunicationIdentifier ve türetilmiş türler (MicrosoftTeamsUserIdentifier, PhoneNumberIdentifiervb.) dize gösterimine (Ham Kimlik) dönüştürülebilir ve dizeden geri yüklenebilir ve bu da aşağıdaki senaryoların uygulanmasını kolaylaştırabilir:

• Tanımlayıcıları bir veritabanında depolayın ve bunları anahtar olarak kullanın.
• Tanımlayıcıları sözlüklerde anahtar olarak kullanın.
• POST yüklerine güvenmek yerine REST API yollarında anahtar olarak tanımlayıcıları kullanarak sezgisel REST CRUD API'lerini uygulayın.
• Gereksiz yeniden işlemeyi önlemek için React gibi bildirim temelli UI çerçevelerinde anahtar olarak tanımlayıcıları kullanın.

CommunicationIdentifier oluşturma ve Ham Kimliği alma

CommunicationIdentifier bir Ham Kimlikten oluşturulabilir ve Bir Ham Kimlik, CommunicationIdentifier'dan türetilen bir türden alınabilir. Yalnızca belirli nesne özelliklerinde alabilen ve diğerlerini atlayan özel serileştirme yöntemlerinin gereksinimini ortadan kaldırır. Örneğin, veya MicrosoftTeamsUserIdentifier gibi IsAnonymous Cloud birden çok özelliğe sahiptir veya bu değerleri almak için yöntemler (platforma bağlı olarak). İletişim Kimliği SDK'sı tarafından sağlanan yöntemlerin kullanılması, daha fazla özellik eklense bile tanımlayıcıları seri hale getirme yönteminin kurallı ve tutarlı kalmasını garanti eder.

CommunicationUserIdentifier'dan Ham Kimlik alma:

public async Task GetRawId()
{
    ChatMessage message = await ChatThreadClient.GetMessageAsync("678f26ef0c");
    CommunicationIdentifier communicationIdentifier = message.Sender;
    String rawId = communicationIdentifier.RawId;
}

Ham Kimlikten CommunicationUserIdentifier Örneği Oluşturma:

public void CommunicationIdentifierFromGetRawId()
{
    String rawId = "8:acs:bbbcbc1e-9f06-482a-b5d8-20e3f26ef0cd_45ab2481-1c1c-4005-be24-0ffb879b1130";
    CommunicationIdentifier communicationIdentifier = CommunicationIdentifier.FromRawId(rawId);
}

Platforma özgü daha fazla örneği şu makalede bulabilirsiniz: Tanımlayıcı türlerini anlama

CommunicationIdentifier'i veritabanında depolama

Sizin için gerekli olabilecek tipik işlerden biri, Azure İletişim Hizmetleri kullanıcıları Contoso kullanıcı veritabanından veya kimlik sağlayıcısından gelen kullanıcılarla eşlemektir. Bu genellikle Contoso kullanıcı db'sinde veya Kimlik Sağlayıcısı'nda fazladan bir sütun veya alan ekleyerek elde edilir. Ancak, Ham Kimliğin özellikleri (kararlı, genel olarak benzersiz ve belirleyici) göz önünde bulundurulduğunda, bunu kullanıcı depolaması için birincil anahtar olarak seçebilirsiniz.

a'nın ContosoUser uygulamanızın bir kullanıcısını temsil eden bir sınıf olduğunu ve bunu veritabanına karşılık gelen bir CommunicationIdentifier ile birlikte kaydetmek istediğinizi varsayarsak. için CommunicationIdentifier özgün değer İletişim Kimliği, Arama veya Sohbet API'lerinden veya özel bir Contoso API'sinden gelebilir, ancak temel alınan tür ne olursa olsun programlama dilinizde bir string veri türü olarak gösterilebilir:

public class ContosoUser
{
    public string Name { get; set; }
    public string Email { get; set; }
    public string CommunicationId { get; set; }
}

veritabanında depolanabilen bir dize almak için 'nin özelliğine CommunicationId erişebilirsinizRawId:

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

    ContosoUser user = new ContosoUser()
    {
        Name = "John",
        Email = "john@doe.com",
        CommunicationId = communicationIdentifier.RawId
    };
    SaveToDb(user);
}

Depolanan Ham Kimlikten almak CommunicationIdentifier istiyorsanız, ham dizeyi yöntemine FromRawId() geçirmeniz gerekir:

public void GetFromDatabase()
{
    ContosoUser user = GetFromDb("john@doe.com");
    CommunicationIdentifier communicationIdentifier = CommunicationIdentifier.FromRawId(user.CommunicationId);
}

Tanımlayıcı türüne göre , MicrosoftTeamsUserIdentifier PhoneNumberIdentifierveya UnknownIdentifier döndürürCommunicationUserIdentifier.

CommunicationIdentifier'i koleksiyonlarda depolama

Senaryonuz bellekte birkaç CommunicationIdentifier nesnesiyle çalışmayı gerektiriyorsa, bunları bir koleksiyonda (sözlük, liste, karma kümesi vb.) depolamak isteyebilirsiniz. Koleksiyon, örneğin arama veya sohbet katılımcılarının listesini tutmak için kullanışlıdır. Karma mantığı ham kimliğin değerine bağlı olduğundan, öğelerin güvenilir karma davranışına sahip olmasını gerektiren koleksiyonlarda CommunicationIdentifier'ı kullanabilirsiniz. Aşağıdaki örnekler, farklı koleksiyon türlerine CommunicationIdentifier nesneleri eklemeyi ve Raw ID değerinden yeni tanımlayıcılar oluşturarak bunların bir koleksiyonda yer alıp almadıklarını denetlemeyi gösterir.

Aşağıdaki örnekte, kullanıcının iletilerini depolamak için Raw ID'nin sözlükte anahtar olarak nasıl kullanılabileceğini gösterilmektedir:

public void StoreMessagesForContosoUsers()
{
    var communicationUser = new CommunicationUserIdentifier("8:acs:bbbcbc1e-9f06-482a-b5d8-20e3f26ef0cd_45ab2481-1c1c-4005-be24-0ffb879b1130");
    var teamsUserUser = new CommunicationUserIdentifier("45ab2481-1c1c-4005-be24-0ffb879b1130");
    
    // A dictionary with a CommunicationIdentifier as key might be used to store messages of a user.
    var userMessages = new Dictionary<string, List<Message>>
    {
        { communicationUser.RawId, new List<Message>() },
        { teamsUserUser.RawId, new List<Message>() },
    };

    // Retrieve messages for a user based on their Raw ID.
    var messages = userMessages[communicationUser.RawId];
}

Karma mantığı ham kimliğin değerine bağlı olduğundan, kendisini doğrudan sözlükte anahtar olarak kullanabilirsiniz CommunicationIdentifier :

public void StoreMessagesForContosoUsers()
{
    // A dictionary with a CommunicationIdentifier as key might be used to store messages of a user.
    var userMessages = new Dictionary<CommunicationIdentifier, List<Message>>
    {
        { new CommunicationUserIdentifier("8:acs:bbbcbc1e-9f06-482a-b5d8-20e3f26ef0cd_45ab2481-1c1c-4005-be24-0ffb879b1130"), new List<Message>() },
        { new MicrosoftTeamsUserIdentifier("45ab2481-1c1c-4005-be24-0ffb879b1130"), new List<Message>() },
    };

    // Retrieve messages for a user based on their Raw ID.
    var messages = userMessages[CommunicationIdentifier.FromRawId("8:acs:bbbcbc1e-9f06-482a-b5d8-20e3f26ef0cd_45ab2481-1c1c-4005-be24-0ffb879b1130")];
}

Ham Kimlik değerini kullanan karma mantığı, karma kümelerine nesne eklemenize CommunicationIdentifier de olanak tanır:

public void StoreUniqueContosoUsers()
{
    // A hash set of unique users of a Contoso application.
    var users = new HashSet<CommunicationIdentifier>
    {
        new PhoneNumberIdentifier("+14255550123"),
        new UnknownIdentifier("28:45ab2481-1c1c-4005-be24-0ffb879b1130")
    };

    // Implement custom flow for a new communication user.
     if (users.Contains(CommunicationIdentifier.FromRawId("4:+14255550123"))){
        //...
     }
}

Diğer bir kullanım örneği de katılımcıları tanımlamak için mobil uygulamalarda Ham Kimlikler kullanmaktır. Bu bilgileri Azure İletişim Hizmetleri göndermeden kullanıcı arabirimi kitaplığında yerel olarak işlemek istiyorsanız, uzak katılımcının katılımcı görünüm verilerini ekleyebilirsiniz. Bu görünüm verileri, işlenmek üzere avatarı temsil eden bir UIImage ve isteğe bağlı olarak görüntüleyebileceği bir görünen ad içerebilir. Uzak katılımcıyı benzersiz bir şekilde tanımlamak için hem katılımcı CommunicationIdentifier hem de ondan alınan Ham Kimlik kullanılabilir.

callComposite.events.onRemoteParticipantJoined = { identifiers in
  for identifier in identifiers {
    // map identifier to displayName
    let participantViewData = ParticipantViewData(displayName: "<DISPLAY_NAME>")
    callComposite.set(remoteParticipantViewData: participantViewData,
                      for: identifier) { result in
      switch result {
      case .success:
        print("Set participant view data succeeded")
      case .failure(let error):
        print("Set participant view data failed with \(error)")
      }
    }
  }
}    

REST API yollarında anahtar olarak Ham Kimlik kullanma

REST API tasarlarken, bir veya Ham Kimlik dizesi kabul CommunicationIdentifier eden uç noktalarınız olabilir. Tanımlayıcı birkaç bölümden oluşuyorsa (objectID, bulut adı vb. kullanıyorsanız MicrosoftTeamsUserIdentifier), bunu istek gövdesine geçirmeniz gerekebilir. Ancak Ham Kimlik kullanmak, bileşik nesnenin tamamını gövdede JSON olarak geçirmek yerine URL yolundaki varlığı ele almanızı sağlar. Böylece daha sezgisel bir REST CRUD API'niz olabilir.

public async Task UseIdentifierInPath()
{
    CommunicationIdentifier user = GetFromDb("john@doe.com");
    
    using HttpResponseMessage response = await client.GetAsync($"https://contoso.com/v1.0/users/{user.RawId}/profile");
    response.EnsureSuccessStatusCode();
}

Ham kimliklerden tanımlayıcı ayrıntıları ayıklanır.

Tutarlı temel ham kimlik şunları sağlar:

• Doğru tanımlayıcı türüne seri durumdan çıkarma (uygulamanızın akışını ayarlayabilmenize bağlı olarak).
• Tanımlayıcıların ayrıntılarını ayıklama (örneğin, için MicrosoftTeamsUserIdentifierbir oid).

Örnekte her iki avantaj da gösterilmektedir:

• Bu tür, avatarın nereden alınacağınıza karar vermenize olanak tanır.
• Ayrıştırılan ayrıntılar, API'yi doğru şekilde sorgulamanıza olanak sağlar.

public void ExtractIdentifierDetails()
{
    ContosoUser user = GetFromDb("john@doe.com");

    string rawId = user.CommunicationIdentifier;
    CommunicationIdentifier teamsUser = CommunicationIdentifier.FromRawId(rawId);
    switch (communicationIdentifier)
    {
        case MicrosoftTeamsUserIdentifier teamsUser:
            string getPhotoUri = $"https://graph.microsoft.com/v1.0/users/{teamsUser.UserId}/photo/$value";
            // ...
            break;
        case CommunicationIdentifier communicationUser:
            string getPhotoUri = GetAvatarFromDB(communicationUser.Id);
            // ...
            break;
    }
}

Contoso veritabanında dize (Ham Kimlik) biçiminde depolanan belirli bir CommunicationIdentifier türünün özelliklerine veya yöntemlerine erişebilirsiniz.

Ui çerçevelerinde anahtar olarak Ham Kimlikleri kullanma

Belirli bir kullanıcıyı izlemek ve gereksiz yeniden işleme ve API çağrılarından kaçınmak için kullanıcı arabirimi bileşenlerinde bir tanımlayıcının Ham Kimliğini anahtar olarak kullanmak mümkündür. Örnekte, kullanıcıların bir listede nasıl işlendiğine ilişkin sırayı değiştiriyoruz. Gerçek dünyada, yeni kullanıcıları önce göstermek veya belirli bir koşula göre kullanıcıları yeniden sıralamak isteyebiliriz (örneğin, el kaldırılmış). Basitlik açısından, aşağıdaki örnek yalnızca kullanıcıların işlenme sırasını tersine çevirir.

import { getIdentifierRawId } from '@azure/communication-common';

function CommunicationParticipants() {
  const [users, setUsers] = React.useState([{ id: getIdentifierRawId(userA), name: "John" }, { id: getIdentifierRawId(userB), name: "Jane" }]);
  return (
    <div>
      {users.map((user) => (
      // React uses keys as hints while rendering elements. Each list item should have a key that's unique among its siblings. 
      // Raw ID can be utilized as a such key.
        <ListUser item={user} key={user.id} />
      ))}
      <button onClick={() => setUsers(users.slice().reverse())}>Reverse</button>
    </div>
  );
}

const ListUser = React.memo(function ListUser({ user }) {
  console.log(`Render ${user.name}`);
  return <div>{user.name}</div>;
});

Sonraki adımlar

Bu makalede şunların nasıl yapılacağını öğrendiniz:

Daha fazla bilgi edinmek için aşağıdaki hızlı başlangıç kılavuzlarını incelemek isteyebilirsiniz:

• Tanımlayıcı türlerini anlama
• Başvuru belgeleri