Hızlı Başlangıç: Arama hizmetine bağlanma

Bu hızlı başlangıçta, Azure AI Search hizmetinize anahtarsız bir bağlantı kurmak için rol tabanlı erişim denetimi (RBAC) ve Microsoft Entra Id kullanacaksınız. Ardından, hizmetinizle etkileşime geçmek için Visual Studio Code'da Python'ı kullanırsınız.

Anahtarsız bağlantılar, ayrıntılı izinler ve kimlik tabanlı kimlik doğrulaması aracılığıyla gelişmiş güvenlik sağlar. Sabit kodlanmış API anahtarları önermiyoruz, ancak bunları tercih ediyorsanız bkz. Anahtarları kullanarak Azure AI Search'e bağlanma.

Önkoşullar

• Aktif bir aboneliğe sahip bir Azure hesabı. Ücretsiz hesap oluşturun.

• Herhangi bir bölgede veya katmanda Azure AI Search hizmeti.

• Microsoft Entra Id ile anahtarsız kimlik doğrulaması için Azure CLI .

• Python uzantısı ve Jupyter paketi ile Visual Studio Code.

Rol tabanlı erişimi yapılandırma

Bu bölümde, Azure AI Search hizmetinizde RBAC'yi etkinleştirip arama nesnelerini oluşturmak, yüklemek ve sorgulamak için gerekli rolleri atayacaksınız. Bu adımlar hakkında daha fazla bilgi için bkz. Rolleri kullanarak Azure AI Search'e bağlanma.

Erişimi yapılandırmak için:

1. Azure portalında oturum açın ve arama hizmetinizi seçin.

2. Sol bölmeden Ayarlar > Anahtarları'nı seçin.

3. İstemcileri RBAC'ye geçirmeniz için zamana ihtiyacınız varsa Rol tabanlı erişim denetimi'ni veya Her İkisi'ni seçin.

   

4. Sol bölmeden Erişim denetimi (IAM) öğesini seçin.

5. Ekle>Rol ataması ekle’yi seçin.

   

6. Arama Hizmeti Katkıda Bulunanı rolünü kullanıcı hesabınıza veya yönetilen kimliğinize atayın.

7. Arama Dizini Veri Katkıda Bulunanı için rol atamasını yineleyin.

Hizmet bilgilerini alma

Bu bölümde Azure AI Search hizmetinizin abonelik kimliğini ve uç noktasını alırsınız. Yalnızca bir aboneliğiniz varsa abonelik kimliğini atlayın ve yalnızca uç noktayı alın. Bu değerleri bu hızlı başlangıcın kalan bölümlerinde kullanırsınız.

Hizmet bilgilerinizi almak için:

1. Azure portalında oturum açın ve arama hizmetinizi seçin.

2. Sol bölmeden Genel Bakış'ı seçin.

3. Abonelik kimliğini ve uç noktayı not edin.

   

Azure'a Giriş Yap

Azure AI Search hizmetinize bağlanmadan önce hizmetinizi içeren abonelikte oturum açmak için Azure CLI'yi kullanın. Bu adım, sonraki bölümde isteklerin kimliğini doğrulamak için kullanan DefaultAzureCredential Microsoft Entra kimliğinizi belirler.

Oturum açmak için:

1. Yerel sisteminizde bir komut satırı aracı açın.

2. Yerel ortamınızda etkin aboneliği ve kiracıyı denetleyin.

   az account show
   

3. Etkin abonelik ve kiracı arama hizmetiniz için geçerli değilse, değerlerini güncelleştirmek için aşağıdaki komutları çalıştırın. Abonelik kimliğini Azure portalındaki arama hizmetine Genel Bakış sayfasında bulabilirsiniz. Kiracı kimliğini bulmak için Genel Bakış sayfasında aboneliğinizin adını seçin ve üst ebeveyn yönetim grubu değerini bulun.

    az account set --subscription <your-subscription-id>
   
    az login --tenant <your-tenant-id>
   

Azure AI Search'e bağlanma

Uyarı

Bu bölümde anahtarsız bağlantılar için temel Python deseni gösterilmektedir. Kapsamlı yönergeler için, Hızlı Başlangıç: Aracılı Alma gibi belirli bir Hızlı Başlangıç veya öğreticiye bakın.

Azure AI Search hizmetinize istek göndermek için Visual Studio Code'daki Python not defterlerini kullanabilirsiniz. İstek kimlik doğrulaması için Azure Kimlik kitaplığındaki sınıfını kullanın DefaultAzureCredential .

Python kullanarak bağlanmak için:

1. Yerel sisteminizde Visual Studio Code'ı açın.

2. Bir .ipynb dosyası oluşturun.

3. azure-identity ve azure-search-documents kitaplıklarını yüklemek için bir kod hücresi oluşturun.

   pip install azure-identity azure-search-documents
   

4. Kimlik doğrulaması yapmak ve arama hizmetinize bağlanmak için başka bir kod hücresi oluşturun.

   from azure.identity import DefaultAzureCredential
   from azure.search.documents.indexes import SearchIndexClient
   
   service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
   credential = DefaultAzureCredential()
   client = SearchIndexClient(endpoint = service_endpoint, credential = credential)
   
   # List existing indexes
   indexes = client.list_indexes()
   
   for index in indexes:
      index_dict = index.as_dict()
      print(json.dumps(index_dict, indent = 2))
   

5. service_endpoint bölümünde elde ettiğiniz değere ayarlayın.

6. Her iki kod hücresini de çalıştırmak için Tümünü Çalıştır'ı seçin.

   Çıktı, arama hizmetinizdeki mevcut dizinleri (varsa) listelemeli ve bağlantının başarılı olduğunu göstermelidir.

401 hatalarını giderme

401 hatasıyla karşılaşırsanız şu sorun giderme adımlarını izleyin:

• Rol tabanlı erişimi yapılandırma'ya yeniden bakın. Arama hizmetinizde Rol tabanlı erişim denetimi veya Her İkisi etkin olmalıdır. Abonelik veya kaynak grubu düzeyindeki ilkeler rol atamalarınızı geçersiz kabilir.

• Azure'da Oturum Açma sayfasını tekrar ziyaret edin. Arama hizmetinizi içeren abonelikte oturum açmanız gerekir.

• Uç nokta değişkeninizin etrafında tırnak işareti olduğundan emin olun.

• Diğer her şey başarısız olursa, önbelleğe alınmış belirteçleri kaldırmak için cihazınızı yeniden başlatın ve ardından Azure'da oturum açma ile başlayarak bu hızlı başlangıçtaki adımları yineleyin.

Bu hızlı başlangıçta, Azure AI Search hizmetinize anahtarsız bir bağlantı kurmak için rol tabanlı erişim denetimi (RBAC) ve Microsoft Entra Id kullanacaksınız. Ardından hizmetinizle etkileşime geçmek için Visual Studio Code'da REST kullanırsınız.

Anahtarsız bağlantılar, ayrıntılı izinler ve kimlik tabanlı kimlik doğrulaması aracılığıyla gelişmiş güvenlik sağlar. Sabit kodlanmış API anahtarları önermiyoruz, ancak bunları tercih ediyorsanız bkz. Anahtarları kullanarak Azure AI Search'e bağlanma.

Önkoşullar

• Aktif bir aboneliğe sahip bir Azure hesabı. Ücretsiz hesap oluşturun.

• Herhangi bir bölgede veya katmanda Azure AI Search hizmeti.

• Microsoft Entra Id ile anahtarsız kimlik doğrulaması için Azure CLI .

• REST İstemci uzantısıylaVisual Studio Code.

Rol tabanlı erişimi yapılandırma

Bu bölümde, Azure AI Search hizmetinizde RBAC'yi etkinleştirip arama nesnelerini oluşturmak, yüklemek ve sorgulamak için gerekli rolleri atayacaksınız. Bu adımlar hakkında daha fazla bilgi için bkz. Rolleri kullanarak Azure AI Search'e bağlanma.

Erişimi yapılandırmak için:

1. Azure portalında oturum açın ve arama hizmetinizi seçin.

2. Sol bölmeden Ayarlar > Anahtarları'nı seçin.

3. İstemcileri RBAC'ye geçirmeniz için zamana ihtiyacınız varsa Rol tabanlı erişim denetimi'ni veya Her İkisi'ni seçin.

   

4. Sol bölmeden Erişim denetimi (IAM) öğesini seçin.

5. Ekle>Rol ataması ekle’yi seçin.

   

6. Arama Hizmeti Katkıda Bulunanı rolünü kullanıcı hesabınıza veya yönetilen kimliğinize atayın.

7. Arama Dizini Veri Katkıda Bulunanı için rol atamasını yineleyin.

Hizmet bilgilerini alma

Bu bölümde Azure AI Search hizmetinizin abonelik kimliğini ve uç noktasını alırsınız. Yalnızca bir aboneliğiniz varsa abonelik kimliğini atlayın ve yalnızca uç noktayı alın. Bu değerleri bu hızlı başlangıcın kalan bölümlerinde kullanırsınız.

Hizmet bilgilerinizi almak için:

1. Azure portalında oturum açın ve arama hizmetinizi seçin.

2. Sol bölmeden Genel Bakış'ı seçin.

3. Abonelik kimliğini ve uç noktayı not edin.

   

Azure'a Giriş Yap

Azure AI Search hizmetinize bağlanmadan önce hizmetinizi içeren abonelikte oturum açmak için Azure CLI'yi kullanın.

Oturum açmak için:

1. Yerel sisteminizde bir komut satırı aracı açın.

2. Yerel ortamınızda etkin aboneliği ve kiracıyı denetleyin.

   az account show
   

3. Etkin abonelik ve kiracı arama hizmetiniz için geçerli değilse, değerlerini güncelleştirmek için aşağıdaki komutları çalıştırın. Abonelik kimliğini Azure portalındaki arama hizmetine Genel Bakış sayfasında bulabilirsiniz. Kiracı kimliğini bulmak için Genel Bakış sayfasında aboneliğinizin adını seçin ve üst ebeveyn yönetim grubu değerini bulun.

    az account set --subscription <your-subscription-id>
   
    az login --tenant <your-tenant-id>
   

Jeton almak

REST API çağrıları bir Microsoft Entra Id belirtecinin eklenmesini gerektirir. Sonraki bölümde isteklerin kimliğini doğrulamak için bu belirteci kullanacaksınız.

Belirtecinizi almak için:

1. Aynı komut satırı aracını kullanarak bir erişim belirteci oluşturun.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

2. Jeton çıkışını not edin.

Azure AI Search'e bağlanma

Uyarı

Bu bölümde anahtarsız bağlantılar için temel REST deseni gösterilmektedir. Kapsamlı yönergeler için, Hızlı Başlangıç: Aracılı Alma gibi belirli bir Hızlı Başlangıç veya öğreticiye bakın.

Azure AI Search hizmetinize istek göndermek için Visual Studio Code'daki REST İstemci uzantısını kullanabilirsiniz. İstek kimlik doğrulaması için, daha önce oluşturduğunuz Microsoft Entra ID belirtecini içeren bir Authorization üst bilgi ekleyin.

REST kullanarak bağlanmak için:

1. Yerel sisteminizde Visual Studio Code'ı açın.

2. .rest veya .http bir dosya oluşturun.

3. Aşağıdaki değişkenleri ve isteği dosyaya yapıştırın.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
   @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
   
   ### List existing indexes
   GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
      Content-Type: application/json
      Authorization: Bearer {{token}}
   

4. @baseUrl bölümünde elde ettiğiniz değere ayarlayın.

5. @token bölümünde elde ettiğiniz değere ayarlayın.

6. altında ### List existing indexesİstek Gönder'i seçin.

   Arama hizmetinizle başarılı bir HTTP/1.1 200 OK bağlantı olduğunu belirten bir yanıt almanız gerekir.

401 hatalarını giderme

401 hatasıyla karşılaşırsanız şu sorun giderme adımlarını izleyin:

• Rol tabanlı erişimi yapılandırma'ya yeniden bakın. Arama hizmetinizde Rol tabanlı erişim denetimi veya Her İkisi etkin olmalıdır. Abonelik veya kaynak grubu düzeyindeki ilkeler rol atamalarınızı geçersiz kabilir.

• Azure'da Oturum Açma sayfasını tekrar ziyaret edin. Arama hizmetinizi içeren abonelikte oturum açmanız gerekir.

• Uç nokta ve belirteç değişkenlerinizin çevresinde tırnak işaretleri veya ek boşluklar olmadığından emin olun.

• Belirtecin, istek üst bilgisinde @ sembolü içermediğinden emin olun. Örneğin, değişken @token ise, istekteki {{token}} başvuru olarak belirtilmelidir.

• Diğer her şey başarısız olursa, önbelleğe alınmış belirteçleri kaldırmak için cihazınızı yeniden başlatın ve ardından Azure'da oturum açma ile başlayarak bu hızlı başlangıçtaki adımları yineleyin.

İlgili içerik

• Azure AI Search'te yönetilen kimlik yapılandırma
• Kimlikleri kullanarak uygulamanızı Azure AI Search'e bağlama
• Azure AI Search için ağ erişimini ve güvenlik duvarı kurallarını yapılandırma