CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-azure-mgmt-search

Microsoft Azure Search Management Client Library for Python

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

key-management.mddocs/

Authentication Key Management

Management of admin and query keys for search service authentication. Admin keys provide full access to the search service for index management and data operations, while query keys provide read-only access specifically for search and lookup operations.

Capabilities

Admin Key Operations

Admin keys provide full administrative access to the search service, enabling index creation, data upload, and service configuration. Each service has two admin keys (primary and secondary) for key rotation scenarios.

def get(
    resource_group_name: str,
    search_service_name: str,
    *,
    client_request_id: Optional[str] = None,
    **kwargs
) -> AdminKeyResult:
    """
    Get the admin API keys for a search service.
    
    Parameters:
        resource_group_name (str): Resource group name
        search_service_name (str): Search service name
        client_request_id (str, optional): Client-generated request ID
        
    Returns:
        AdminKeyResult: Container with primary and secondary admin keys
        
    Raises:
        ResourceNotFoundError: Service does not exist
        HttpResponseError: Access denied or service error
    """

def regenerate(
    resource_group_name: str,
    search_service_name: str,
    key_kind: AdminKeyKind,
    *,
    client_request_id: Optional[str] = None,
    **kwargs
) -> AdminKeyResult:
    """
    Regenerate either the primary or secondary admin key.
    
    Parameters:
        resource_group_name (str): Resource group name
        search_service_name (str): Search service name
        key_kind (AdminKeyKind): Which key to regenerate (primary or secondary)
        client_request_id (str, optional): Client-generated request ID
        
    Returns:
        AdminKeyResult: Updated admin keys with new regenerated key
        
    Raises:
        ResourceNotFoundError: Service does not exist
        HttpResponseError: Access denied or invalid key kind
    """

Usage Example:

from azure.mgmt.search.models import AdminKeyKind

# Get current admin keys
admin_keys = client.admin_keys.get("my-resource-group", "my-search-service")
print(f"Primary Key: {admin_keys.primary_key}")
print(f"Secondary Key: {admin_keys.secondary_key}")

# Regenerate the primary admin key (for key rotation)
new_keys = client.admin_keys.regenerate(
    resource_group_name="my-resource-group",
    search_service_name="my-search-service",
    key_kind=AdminKeyKind.PRIMARY
)
print(f"New Primary Key: {new_keys.primary_key}")
print(f"Secondary Key (unchanged): {new_keys.secondary_key}")

# Best practice: Use secondary key in applications, then regenerate primary,
# update applications to use new primary, then regenerate secondary

Query Key Operations

Query keys provide read-only access for search operations. Unlike admin keys, you can create multiple query keys and delete individual keys as needed for different applications or users.

def create(
    resource_group_name: str,
    search_service_name: str,
    name: str,
    *,
    client_request_id: Optional[str] = None,
    **kwargs
) -> QueryKey:
    """
    Create a new query API key.
    
    Parameters:
        resource_group_name (str): Resource group name
        search_service_name (str): Search service name
        name (str): Descriptive name for the query key
        client_request_id (str, optional): Client-generated request ID
        
    Returns:
        QueryKey: The new query key with name and key value
        
    Raises:
        ResourceNotFoundError: Service does not exist
        HttpResponseError: Access denied or quota exceeded
    """

def list_by_search_service(
    resource_group_name: str,
    search_service_name: str,
    *,
    client_request_id: Optional[str] = None,
    **kwargs
) -> ItemPaged[QueryKey]:
    """
    List all query keys for a search service.
    
    Parameters:
        resource_group_name (str): Resource group name
        search_service_name (str): Search service name
        client_request_id (str, optional): Client-generated request ID
        
    Returns:
        ItemPaged[QueryKey]: Paginated list of query keys
        
    Raises:
        ResourceNotFoundError: Service does not exist
    """

def delete(
    resource_group_name: str,
    search_service_name: str,
    key: str,
    *,
    client_request_id: Optional[str] = None,
    **kwargs
) -> None:
    """
    Delete a query key by its key value.
    
    Parameters:
        resource_group_name (str): Resource group name
        search_service_name (str): Search service name
        key (str): The query key value to delete
        client_request_id (str, optional): Client-generated request ID
        
    Raises:
        ResourceNotFoundError: Service or key does not exist
    """

Usage Example:

# Create query keys for different applications
web_app_key = client.query_keys.create(
    resource_group_name="my-resource-group",
    search_service_name="my-search-service",
    name="web-application"
)
print(f"Web App Key: {web_app_key.key}")

mobile_app_key = client.query_keys.create(
    resource_group_name="my-resource-group",
    search_service_name="my-search-service",
    name="mobile-application"
)
print(f"Mobile App Key: {mobile_app_key.key}")

# List all query keys
query_keys = client.query_keys.list_by_search_service(
    "my-resource-group", 
    "my-search-service"
)
for key in query_keys:
    print(f"Query Key: {key.name} - {key.key}")

# Delete a specific query key
client.query_keys.delete(
    resource_group_name="my-resource-group",
    search_service_name="my-search-service",
    key=mobile_app_key.key
)
print("Mobile app key deleted")

Data Models

AdminKeyResult

Container for the two admin API keys that provide full service access.

class AdminKeyResult:
    """
    Admin API keys for full search service access.
    
    Attributes:
        primary_key (str): Primary admin key for full service access
        secondary_key (str): Secondary admin key for full service access
    """

QueryKey

Individual query API key for read-only search access.

class QueryKey:
    """
    Query API key for read-only search operations.
    
    Attributes:
        name (str): Descriptive name assigned to the key
        key (str): The actual API key value used for authentication
    """

AdminKeyKind

Enumeration specifying which admin key to regenerate.

class AdminKeyKind(str, Enum):
    """Admin key types for regeneration operations."""
    PRIMARY = "primary"
    SECONDARY = "secondary"

Key Management Best Practices

Admin Key Rotation

# Safe admin key rotation pattern
# Step 1: Applications should use secondary key
current_keys = client.admin_keys.get("rg", "service")
print(f"Use secondary key in apps: {current_keys.secondary_key}")

# Step 2: Regenerate primary key
new_keys = client.admin_keys.regenerate("rg", "service", AdminKeyKind.PRIMARY)
print(f"New primary key: {new_keys.primary_key}")

# Step 3: Update applications to use new primary key
# Step 4: Regenerate secondary key
final_keys = client.admin_keys.regenerate("rg", "service", AdminKeyKind.SECONDARY)
print(f"Both keys rotated successfully")

Query Key Management

# Create application-specific query keys
apps = ["web-frontend", "mobile-app", "reporting-service", "analytics-dashboard"]
created_keys = {}

for app_name in apps:
    key = client.query_keys.create("rg", "service", app_name)
    created_keys[app_name] = key.key
    print(f"Created key for {app_name}: {key.key}")

# Later: Remove access for specific application
app_to_remove = "analytics-dashboard"
if app_to_remove in created_keys:
    client.query_keys.delete("rg", "service", created_keys[app_to_remove])
    print(f"Removed access for {app_to_remove}")

Key Usage Scenarios

Admin Keys are used for:

  • Index creation, updating, and deletion
  • Data upload and document management
  • Service configuration changes
  • Creating and managing data sources and indexers
  • Managing skillsets and synonym maps

Query Keys are used for:

  • Search requests (POST /indexes/{index}/docs/search)
  • Lookup requests (GET /indexes/{index}/docs/{key})
  • Suggest requests (POST /indexes/{index}/docs/suggest)
  • Autocomplete requests (POST /indexes/{index}/docs/autocomplete)

Security Considerations

# Store keys securely - never in source code
import os
from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

# Store admin key in Key Vault
credential = DefaultAzureCredential()
kv_client = SecretClient("https://my-vault.vault.azure.net/", credential)

admin_keys = client.admin_keys.get("rg", "service")
kv_client.set_secret("search-admin-key", admin_keys.primary_key)

# Retrieve key when needed
admin_key = kv_client.get_secret("search-admin-key").value

Install with Tessl CLI

npx tessl i tessl/pypi-azure-mgmt-search

docs

index.md

key-management.md

network-security.md

private-networking.md

service-management.md

usage-monitoring.md

tile.json