Udostępnij za pośrednictwem

Dodawanie, aktualizowanie lub usuwanie dokumentów (interfejs API REST w wersji zapoznawczej)

  • Artykuł

Dotyczy: 2023-07-01-Preview. Ta wersja nie jest już obsługiwana. Uaktualnij natychmiast do nowszej wersji.

Ważny

2023-07-01-Preview dodaje:

  • Obsługa pól wektorowych w dokumencie.

Dokumenty zawierające pola wektorowe można wypchnąć do określonego indeksu przy użyciu protokołu HTTP POST. W przypadku dużej aktualizacji przetwarzanie wsadowe (do 1000 dokumentów na partię lub około 16 MB na partię) zwiększa wydajność indeksowania.

POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2023-07-01-Preview  
  Content-Type: application/json   
  api-key: [admin key]

Parametry identyfikatora URI

Parametr Opis
nazwa usługi Wymagane. Ustaw tę wartość na unikatową, zdefiniowaną przez użytkownika nazwę usługi wyszukiwania.
nazwa indeksu Wymagane. Ustaw tę wartość na nazwę indeksu odbierającego dokumenty. Dokumenty można publikować tylko w jednym indeksie jednocześnie.
wersja interfejsu API Aby uzyskać więcej wersji, zobacz wersje interfejsu API.

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.

Pola Opis
Typ zawartości Wymagane. Ustaw tę wartość na application/json
api-key Opcjonalnie, jeśli używasz ról platformy Azure i token elementu nośnego jest udostępniany w żądaniu, w przeciwnym razie wymagany jest klucz. Klucz api-key to unikatowy, generowany przez system ciąg, który uwierzytelnia żądanie w usłudze wyszukiwania. Przekazywanie dokumentów wymaga klucza interfejsu API administratora. Aby uzyskać szczegółowe informacje, zobacz Connect to Azure AI Search using key authentication (Łączenie z usługą Azure AI Search przy użyciu uwierzytelniania kluczy).

Treść żądania

Treść żądania zawiera co najmniej jeden dokument do indeksowania. Dokumenty są jednoznacznie identyfikowane za pomocą klucza z uwzględnieniem wielkości liter. Każdy dokument jest skojarzony z akcją: "upload", "delete", "merge" lub "mergeOrUpload". Żądania przekazywania muszą zawierać dane dokumentu jako zestaw par klucz/wartość.

Pola wektorowe są typu Collection(Edm.Single). Dane wektorowe składają się z tablicy liczb zmiennoprzecinkowych o pojedynczej precyzji.

Pola wektorowe mogą zawierać tysiące osadzania, w zależności od złożoności, długości lub typu oryginalnej zawartości. Usługa Azure AI Search nie konwertuje zawartości na osadzanie. Dokumenty wypychane do indeksu muszą zawierać wcześniej wygenerowane osadzanie.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (key/value pairs matching index schema),
      "vector_field_name": [ array of single-precision floating point numbers ]
        ...  
    },  
    ...  
  ]  
}
Własność Opis
@search.action Wymagane. Prawidłowe wartości to "upload", "delete", "merge" lub "mergeOrUpload". Wartość domyślna to "upload".
key_field_name Wymagane. Definicja pola w indeksie, który służy jako klucz dokumentu i zawiera tylko unikatowe wartości. Klucze dokumentów mogą zawierać tylko litery, cyfry, kreski ("-"), podkreślenia ("_") i znaki równości ("=") i uwzględniane są wielkość liter.
field_name Wymagane. Pary name-value, gdzie nazwa pola odpowiada nazwie pola w definicji indeksu. Wartość jest zdefiniowana przez użytkownika, ale musi być prawidłowa dla typu pola.

Odpowiedź

Kod stanu: 200 jest zwracany dla pomyślnej odpowiedzi, co oznacza, że wszystkie elementy zostały trwale przechowywane i że indeksowanie zostało rozpoczęte. Indeksowanie jest uruchamiane w tle i udostępnia nowe dokumenty (czyli z możliwością wykonywania zapytań i wyszukiwania) kilka sekund po zakończeniu operacji indeksowania.

Pomyślne indeksowanie jest wskazywane, gdy właściwość statusu ustawiona na wartość true dla wszystkich elementów. Właściwość statusCode powinna mieć wartość 201 (dla nowo przekazanych dokumentów) lub 200 (dla scalonych lub usuniętych dokumentów).

Przykłady

Przykład: przekazywanie dwóch dokumentów przy użyciu zawartości tekstowej i wektorowej

W celu zapewnienia czytelności w poniższym przykładzie przedstawiono podzbiór dokumentów i osadzania. Treść żądania Przekazywania dokumentów składa się z 108 dokumentów, z których każdy ma pełny zestaw osadzonych elementów "titleVector" i "contentVector".

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "value": [
        {
            "id": "1",
            "title": "Azure App Service",
            "content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
            "category": "Web",
            "titleVector": [
                -0.02250031754374504,
                 . . . 
                        ],
            "contentVector": [
                -0.024740582332015038,
                 . . .
            ],
            "@search.action": "upload"
        },
        {
            "id": "2",
            "title": "Azure Functions",
            "content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
            "category": "Compute",
            "titleVector": [
                -0.020159931853413582,
                . . .
            ],
            "contentVector": [
                -0.02780858241021633,,
                 . . .
            ],
            "@search.action": "upload"
        }
        . . .
    ]
}

Nuta

Podczas przekazywania wartości DateTimeOffset z informacjami o strefie czasowej do indeksu usługa Azure AI Search normalizuje te wartości do czasu UTC. Na przykład 2019-01-13T14:03:00-08:00 będzie przechowywany jako 2019-01-13T22:03:00Z. Jeśli chcesz przechowywać informacje o strefie czasowej, dodaj dodatkową kolumnę do indeksu.

Zobacz też