Partilhar via


Catálogo

O catálogo é um recurso que registra todas as operações de pacote em uma origem de pacote, como criações e exclusões. O recurso de catálogo tem o tipo de Catalog no índice de serviço. Você pode usar esse recurso para consultar todos os pacotes publicados.

Observação

Como o catálogo não é usado pelo cliente do NuGet oficial, nem todas as origens do pacote implementam o catálogo.

Observação

Atualmente, o catálogo nuget.org não está disponível na China. Para obter mais detalhes, consulte NuGet/NuGetGallery#4949.

Controle de versão

O seguinte valor @type é usado:

@type valor Observações
Catalog/3.0.0 O lançamento inicial

URL base

A URL do ponto de entrada para as APIs a seguir é o valor da propriedade @id associada aos valores de @type de recurso mencionados anteriormente. Este tópico usa a URL do espaço reservado {@id}.

Métodos HTTP

Todas as URLs encontradas no recurso de catálogo oferecem suporte apenas aos métodos HTTP GET e HEAD.

Índice do catálogo

O índice de catálogo é um documento em um local conhecido que tem uma lista de itens de catálogo, ordenados cronologicamente. É o ponto de entrada do recurso de catálogo.

O índice é composto por páginas de catálogo. Cada página de catálogo contém itens de catálogo. Cada item de catálogo representa um evento referente a um único pacote em um ponto no tempo. Um item de catálogo pode representar um pacote que foi criado, não listado, relistado ou excluído da origem do pacote. Ao processar os itens de catálogo em ordem cronológica, o cliente pode criar uma exibição atualizada de cada pacote existente na origem do pacote V3.

Em resumo, os blobs de catálogo têm a seguinte estrutura hierárquica:

  • Índice: o ponto de entrada para o catálogo.
  • Página: um agrupamento de itens de catálogo.
  • Folha: um documento que representa um item de catálogo, que é um instantâneo do estado de um único pacote.

Cada objeto de catálogo tem uma propriedade chamada commitTimeStamp representando quando o item foi adicionado ao catálogo. Os itens de catálogo são adicionados a uma página de catálogo em lotes chamados commits. Todos os itens de catálogo no mesmo commit têm o mesmo carimbo de data/hora de commit (commitTimeStamp) e ID de commit (commitId). Os itens de catálogo colocados no mesmo commit representam eventos que aconteceram no mesmo momento na origem do pacote. Não há nenhum pedido dentro de um commit de catálogo.

Como cada ID e versão do pacote são exclusivos, nunca haverá mais de um item de catálogo em um commit. Isso garante que os itens de catálogo de um único pacote sempre possam ser ordenados de forma inequívoca em relação o commit de carimbo de data/hora.

Nunca haverá mais de um commit para o catálogo por commitTimeStamp. Em outras palavras, o commitId é redundante com o commitTimeStamp.

Em contraste com o recurso de metadados do pacote, que é indexado pela ID do pacote, o catálogo é indexado (e consultável) apenas por tempo.

Os itens de catálogo são sempre adicionados ao catálogo em uma ordem cronológica monotonicamente crescente. Isso significa que, se um commit de catálogo for adicionado no tempo X, nenhuma confirmação de catálogo será adicionada com um tempo menor ou igual a X.

A solicitação a seguir busca o índice do catálogo.

GET {@id}

O índice de catálogo é um documento JSON que contém um objeto com as seguintes propriedades:

Nome Digitar Obrigatória Observações
commitId string sim Uma ID exclusiva associada ao commit mais recente
commitTimeStamp string sim Um carimbo de data/hora do commit mais recente
contagem inteiro sim O número de páginas no índice
itens matriz de objetos sim Uma matriz de objetos, cada objeto representando uma página

Cada elemento na matriz items é um objeto com alguns detalhes mínimos sobre cada página. Esses objetos de página não contêm as folhas de catálogo (itens). A ordem dos elementos nessa matriz não está definida. As páginas podem ser ordenadas pelo cliente na memória usando sua propriedade commitTimeStamp.

À medida que novas páginas são introduzidas, o count será incrementado e novos objetos aparecerão na matriz items.

À medida que os itens são adicionados ao catálogo, o commitId do índice será alterado e commitTimeStamp aumentará. Essas duas propriedades são essencialmente um resumo sobre toda a página de commitId e valores commitTimeStamp na matriz items.

Objeto de página de catálogo no índice

Os objetos de página de catálogo encontrados na propriedade de items do índice de catálogo têm as seguintes propriedades:

Nome Digitar Obrigatória Observações
@id string sim A URL para buscar a página do catálogo
commitId string sim Uma ID exclusiva associada ao commit mais recente nesta página
commitTimeStamp string sim Um carimbo de data/hora do commit mais recente nesta página
contagem inteiro sim O número total de itens na página do catálogo

Em contraste com o recurso de metadados do pacote, que, em alguns casos, as folhas embutidas no índice, as folhas de catálogo nunca são inseridas no índice e sempre devem ser buscadas usando a URL do @id da página.

Solicitação de exemplo

GET https://api.nuget.org/v3/catalog0/index.json

Resposta de exemplo

{
  "commitId": "3d698852-eefb-48ed-8f55-9ee357540d20",
  "commitTimeStamp": "2017-10-31T23:33:17.0954363Z",
  "count": 3,
  "items": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/page0.json",
      "commitId": "3a4df280-3d86-458e-a713-4c91ca261fef",
      "commitTimeStamp": "2015-02-01T06:30:11.7477681Z",
      "count": 540
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/page1.json",
      "commitId": "8bcd3cbf-74f0-47a2-a7ae-b7ecc50005d3",
      "commitTimeStamp": "2015-02-01T06:39:53.9553899Z",
      "count": 540
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/page2.json",
      "commitId": "3d698852-eefb-48ed-8f55-9ee357540d20",
      "commitTimeStamp": "2017-10-31T23:33:17.0954363Z",
      "count": 47
    }
  ]
}

Página do catálogo

A página de catálogo é uma coleção de itens de catálogo. É um documento obtido usando um dos valores de @id encontrados no índice de catálogo. A URL para uma página de catálogo não se destina a ser previsível e deve ser descoberta usando apenas o índice de catálogo.

Novos itens de catálogo são adicionados à página no índice de catálogo somente com o carimbo de data/hora de commit mais alto ou a uma nova página. Depois que uma página com um carimbo de data/hora de commit mais alto é adicionada ao catálogo, as páginas mais antigas nunca são adicionadas ou alteradas.

O documento de página de catálogo é um objeto JSON com as seguintes propriedades:

Nome Digitar Obrigatória Observações
commitId string sim Uma ID exclusiva associada ao commit mais recente nesta página
commitTimeStamp string sim Um carimbo de data/hora do commit mais recente nesta página
contagem inteiro sim O número de itens na página
itens matriz de objetos sim Os itens de catálogo nesta página
primário string sim Uma URL para o índice do catálogo

Cada elemento na matriz items é um objeto com alguns detalhes mínimos sobre o item de catálogo. Esses objetos de item não contêm todos os dados do item de catálogo. A ordem dos itens na matriz items da página não está definida. Os itens podem ser encomendados pelo cliente na memória usando sua propriedade commitTimeStamp.

O número de itens de catálogo em uma página é definido pela implementação do servidor. No nuget.org, há no máximo 550 itens em cada página, embora o número real possa ser menor para algumas páginas, dependendo do tamanho do próximo lote de commit no momento.

À medida que novos itens são introduzidos, o count é incrementado e novos objetos de itens de catálogo aparecem na matriz items.

À medida que os itens são adicionados à página, commitId é alterado e commitTimeStamp aumenta. Essas duas propriedades são essencialmente um resumo sobre todos valores de commitId e commitTimeStamp na matriz items.

Objeto de item de catálogo em uma página

Os objetos de item de catálogo encontrados na propriedade de items da página de catálogo têm as seguintes propriedades:

Nome Digitar Obrigatória Observações
@id string sim A URL para buscar o item de catálogo
@type string sim O tipo de item do catálogo
commitId string sim A ID de commit associada a este item de catálogo
commitTimeStamp string sim O carimbo de data/hora de commit deste item de catálogo
nuget:id string sim A ID do pacote à qual esta folha está relacionada
nuget:version string sim A versão do pacote à qual esta folha está relacionada

O valor de @type pode ser um dos seguintes:

  1. nuget:PackageDetails: isso corresponde ao tipo de PackageDetails no documento folha de catálogo.
  2. nuget:PackageDelete: corresponde ao tipo de PackageDelete no documento folha de catálogo.

Para obter mais detalhes sobre o que cada tipo significa, consulte o tipo de itens correspondentes abaixo.

Solicitação de exemplo

GET https://api.nuget.org/v3/catalog0/page2926.json

Resposta de exemplo

{
  "commitId": "616117f5-d9dd-4664-82b9-74d87169bbe9",
  "commitTimeStamp": "2017-10-31T23:30:32.4197849Z",
  "count": 5,
  "parent": "https://api.nuget.org/v3/catalog0/index.json",
  "items": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.23.30.32/util.biz.payments.0.0.4-preview.json",
      "@type": "nuget:PackageDetails",
      "commitId": "616117f5-d9dd-4664-82b9-74d87169bbe9",
      "commitTimeStamp": "2017-10-31T23:30:32.4197849Z",
      "nuget:id": "Util.Biz.Payments",
      "nuget:version": "0.0.4-preview"
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.23.28.02/util.biz.0.0.4-preview.json",
      "@type": "nuget:PackageDetails",
      "commitId": "820340b2-97e3-4f93-b82e-bc85550a6560",
      "commitTimeStamp": "2017-10-31T23:28:02.788239Z",
      "nuget:id": "Util.Biz",
      "nuget:version": "0.0.4-preview"
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.data.1.0.0-preview1-00258.json",
      "@type": "nuget:PackageDetails",
      "commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
      "commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
      "nuget:id": "SourceCode.Clay.Data",
      "nuget:version": "1.0.0-preview1-00258"
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.1.0.0-preview1-00258.json",
      "@type": "nuget:PackageDetails",
      "commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
      "commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
      "nuget:id": "SourceCode.Clay",
      "nuget:version": "1.0.0-preview1-00258"
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.json.1.0.0-preview1-00258.json",
      "@type": "nuget:PackageDetails",
      "commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
      "commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
      "nuget:id": "SourceCode.Clay.Json",
      "nuget:version": "1.0.0-preview1-00258"
    }
  ]
}

Folha de catálogo

A folha de catálogo contém metadados sobre uma ID e versão de pacote específicas em algum momento. É um documento buscado usando o valor de @id encontrado em uma página de catálogo. A URL para uma folha de catálogo não se destina a ser previsível e deve ser descoberta usando apenas uma página de catálogo.

O documento de uma folha de catálogo é um objeto JSON com as seguintes propriedades:

Nome Digitar Obrigatória Observações
@type cadeia de caracteres ou matriz de cadeias de caracteres sim Os tipos de itens do catálogo
catalog:commitId string sim Uma ID do commit associada a este item de catálogo
catalog:commitTimeStamp string sim O carimbo de data/hora de commit deste item de catálogo
ID cadeia de caracteres sim A ID do pacote do item de catálogo
published string sim A data de publicação do item de catálogo de pacotes
version string sim A versão do pacote do item de catálogo

Tipos de Item

A propriedade @type é uma cadeia de caracteres ou matriz de cadeias de caracteres. Por conveniência, se o valor de @type for uma cadeia de caracteres, ele deverá ser tratado como qualquer matriz de tamanho um. Nem todos os valores possíveis para @type são documentados. No entanto, cada item de catálogo tem exatamente um dos dois seguintes valores de tipo de cadeia de caracteres:

  1. PackageDetails: representa um instantâneo dos metadados do pacote
  2. PackageDelete: representa um pacote que foi excluído

Itens do catálogo de detalhes do pacote

Os itens de catálogo com o PackageDetails de tipo contêm um instantâneo dos metadados do pacote para um pacote específico (combinação de ID e versão). Um item de catálogo de detalhes do pacote é produzido quando uma origem de pacote encontra qualquer um dos seguintes cenários:

  1. Um pacote é enviado por push.
  2. Um pacote é relistado.
  3. Um pacote não está listado.
  4. Um pacote foi preterido.
  5. Um pacote não foi preterido.
  6. Um pacote é refluído.
  7. O status de vulnerabilidade de um pacote é atualizado.

Um refluxo de pacote é um gesto administrativo que essencialmente gera um envio por push falso de um pacote existente sem alterações no próprio pacote. Em nuget.org, um refluxo é usado após a correção de um bug em um dos trabalhos em segundo plano que consomem o catálogo.

Os clientes que consomem os itens de catálogo não devem tentar determinar qual desses cenários produziu o item de catálogo. Em vez disso, o cliente deve simplesmente atualizar qualquer exibição ou índice mantido com os metadados contidos no item de catálogo. Além disso, itens de catálogo duplicados ou redundantes devem ser manipulados normalmente (idempotente).

Os itens de catálogo de detalhes do pacote têm as seguintes propriedades, além daquelas incluídas em todas as folhas de catálogo.

Nome Digitar Obrigatória Observações
authors string não
criado string não Um carimbo de data/hora de quando o pacote foi criado pela primeira vez. Propriedade de fallback: published.
dependencyGroups matriz de objetos não As dependências do pacote, agrupadas por estrutura de destino (mesmo formato do recurso de metadados do pacote)
depreciação objeto não A depreciação associada ao pacote (mesmo formato do recurso de metadados do pacote)
descrição string não
iconUrl string não
é Pré-lançamento boolean não Se a versão do pacote é ou não de pré-lançamento. Pode ser detectado a partir de version.
linguagem string não
licenseUrl string não
listados boolean não Se o pacote está ou não listado
minClientVersion string não
packageHash string sim O hash do pacote, codificação usando a base padrão 64
packageHashAlgorithm string sim
packageSize Número inteiro sim O tamanho do pacote .nupkg em bytes
packageTypes matriz de objetos não Os tipos de pacote especificados pelo autor.
projectUrl string não
releaseNotes string não
requireLicenseAgreement boolean não Assuma como false se excluído
summary string não
marcas matriz de cadeias de caracteres não
title string não
verbatimVersion string não A cadeia de caracteres da versão como ela é originalmente encontrada no .nuspec
vulnerabilities matriz de objetos não As vulnerabilidades de segurança do pacote

A propriedade version do pacote é a cadeia de caracteres de versão completa após a normalização. Isso significa que os dados de compilação do SemVer 2.0.0 podem ser incluídos aqui.

O carimbo de data/hora created é quando o pacote foi recebido pela primeira vez pela origem do pacote, que normalmente é pouco tempo antes do carimbo de data/hora de commit do item de catálogo.

O packageHashAlgorithm é uma cadeia de caracteres definida pela implementação do servidor que representa o algoritmo de hash usado para produzir o packageHash. nuget.org sempre usou o valor packageHashAlgorithm de SHA512.

A propriedade packageTypes só estará presente se um tipo de pacote foi especificado pelo autor. Se estiver presente, sempre terá pelo menos 1 (uma) entrada. Cada item da matriz packageTypes é um objeto JSON com as seguintes propriedades:

Nome Digitar Obrigatória Observações
name string sim O nome do tipo de pacote.
version string não A versão do tipo de pacote. Só presente se o autor especificar explicitamente uma versão no nuspec.

O carimbo de data/hora published é a hora em que o pacote foi listado pela última vez.

Observação

Em nuget.org, o valor de published é definido como o ano de 1900 quando o pacote não é listado.

Vulnerabilidades

Uma matriz de objetos vulnerability. Cada vulnerabilidade tem as seguintes propriedades:

Nome Digitar Obrigatória Observações
advisoryUrl string sim Localização do aviso de segurança para o pacote
severidade string sim Gravidade do aviso: “0” = Baixa, “1” = Moderada, “2” = Alta, “3” = Crítica

Se a propriedade severity contiver valores diferentes dos listados aqui, a gravidade do aviso deve ser tratada como baixa.

Solicitação de exemplo

GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json

Resposta de exemplo

{
  "@type": [
    "PackageDetails",
    "catalog:Permalink"
  ],
  "authors": "NuGet.org Team",
  "catalog:commitId": "49fe04d8-5694-45a5-9822-3be61bda871b",
  "catalog:commitTimeStamp": "2015-02-01T11:18:40.8589193Z",
  "created": "2011-12-02T20:21:23.74Z",
  "description": "This package is an example for the V3 protocol.",
  "deprecation": {
    "reasons": [
      "Legacy",
      "HasCriticalBugs",
      "Other"
    ],
    "message": "This package is an example--it should not be used!",
    "alternatePackage": {
      "id": "Newtonsoft.JSON",
      "range": "12.0.2"
    }
  },
  "iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
  "id": "NuGet.Protocol.V3.Example",
  "isPrerelease": false,
  "language": "en-US",
  "licenseUrl": "http://www.opensource.org/licenses/ms-pl",
  "packageHash": "2edCwKLcbcgFJpsAwa883BLtOy8bZpWwbQpiIb71E74k5t2f2WzXEGWbPwntRleUEgSrcxJrh9Orm/TAmgO4NQ==",
  "packageHashAlgorithm": "SHA512",
  "packageSize": 118348,
  "packageTypes": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#packagetypes/DotnetTool",
      "@type": "PackageType",
      "name": "DotnetTool"
    }
  ],
  "projectUrl": "https://github.com/NuGet/NuGetGallery",
  "published": "1900-01-01T00:00:00Z",
  "requireLicenseAcceptance": false,
  "title": "NuGet V3 Protocol Example",
  "version": "1.0.0",
  "dependencyGroups": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup",
      "@type": "PackageDependencyGroup",
      "dependencies": [
        {
          "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/aspnet.suppressformsredirect",
          "@type": "PackageDependency",
          "id": "aspnet.suppressformsredirect",
          "range": "[0.0.1.4, )"
        },
        {
          "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/webactivator",
          "@type": "PackageDependency",
          "id": "WebActivator",
          "range": "[1.4.4, )"
        },
        {
          "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/webapi.all",
          "@type": "PackageDependency",
          "id": "WebApi.All",
          "range": "[0.5.0, )"
        }
      ],
      "targetFramework": ".NETFramework4.6"
    }
  ],
  "tags": [
    "NuGet",
    "V3",
    "Protocol",
    "Example"
  ],
  "vulnerabilities": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#vulnerability/GitHub/999",
      "@type": "Vulnerability",
      "advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
      "severity": "2"
    }
  ]
}

Itens de catálogo de exclusão de pacote

Os itens de catálogo com o tipo PackageDelete contêm um conjunto mínimo de informações indicando aos clientes de catálogo que um pacote foi excluído da origem do pacote e não está mais disponível para qualquer operação de pacote (como restauração).

Observação

É possível que um pacote seja excluído e posteriormente republicado usando a mesma ID e versão do pacote. Em nuget.org, este é um caso muito raro, pois quebra a pressuposição do cliente oficial de que uma ID e uma versão do pacote implicam um conteúdo específico do pacote. Para obter mais informações sobre a exclusão de pacotes no nuget.org, consulte nossa política.

Os itens de catálogo de exclusão de pacote não têm propriedades adicionais além daquelas incluídas em todas as folhas de catálogo.

A propriedade version é a cadeia de caracteres da versão original encontrada no pacote .nuspec.

A propriedade published é a hora em que o pacote foi excluído, que normalmente é tão curto quanto tempo antes do carimbo de data/hora de confirmação do item de catálogo.

Solicitação de exemplo

GET https://api.nuget.org/v3/catalog0/data/2017.11.02.00.40.00/netstandard1.4_lib.1.0.0-test.json

Resposta de exemplo

{
  "@type": [
    "PackageDelete",
    "catalog:Permalink"
  ],
  "catalog:commitId": "19fec5b4-9335-4e4b-bd50-8d5d3f734597",
  "catalog:commitTimeStamp": "2017-11-02T00:40:00.1969812Z",
  "id": "netstandard1.4_lib",
  "originalId": "netstandard1.4_lib",
  "published": "2017-11-02T00:37:43.7181952Z",
  "version": "1.0.0-test"
}

Cursor

Visão geral

Esta seção descreve um conceito de cliente que, embora não seja necessariamente obrigatório pelo protocolo, deve fazer parte de qualquer implementação prática de cliente de catálogo.

Como o catálogo é uma estrutura de dados somente acréscimo indexada por tempo, o cliente deve armazenar um cursor localmente, representando até que ponto no tempo o cliente processou itens de catálogo. Observe que esse valor de cursor nunca deve ser gerado usando o relógio do computador do cliente. Em vez disso, o valor deve vir do valor de commitTimestamp de um objeto de catálogo.

Sempre que o cliente deseja processar novos eventos na origem do pacote, ele só precisa consultar o catálogo para todos os itens com um carimbo de data/hora de confirmação maior do que o cursor armazenado. Depois que o cliente processa com êxito todos os novos itens de catálogo, ele registra o carimbo de data/hora de confirmação mais recente dos itens de catálogo processados como seu novo valor de cursor.

Usando essa abordagem, o cliente pode ter certeza de nunca perder nenhum evento de pacote que ocorreu na origem do pacote. Além disso, o cliente nunca precisa reprocessar eventos antigos anteriores ao carimbo de data/hora de confirmação registrado do cursor.

Esse poderoso conceito de cursores é usado em muitos trabalhos em segundo plano no nuget.org e é usado para manter a própria API V3 atualizada.

Valor inicial

Quando o cliente de catálogo é iniciado pela primeira vez (e, portanto, não tem valor de cursor), ele deve usar um valor de cursor padrão de System.DateTimeOffset.MinValue do .NET ou alguma noção análoga de carimbo de data/hora mínimo representável.

Iteração sobre itens de catálogo

Para consultar o próximo conjunto de itens de catálogo a serem processados, o cliente deve:

  1. Buscar o valor do cursor gravado em um repositório local.
  2. Baixe e desserialize o índice do catálogo.
  3. Localize todas as páginas do catálogo com um carimbo de data/hora de confirmação maior que o cursor.
  4. Declare uma lista vazia de itens de catálogo a serem processados.
  5. Para cada página de catálogo correspondente na etapa 3:
    1. Baixe e desserialize a página do catálogo.
    2. Localize todos os itens de catálogo com um carimbo de data/ hora de confirmação maior que o cursor.
    3. Adicione todos os itens de catálogo correspondentes à lista declarada na etapa 4.
  6. Classifique a lista de itens de catálogo por carimbo de data/hora de confirmação.
  7. Processe cada item do catálogo em sequência:
    1. Baixe e desserialize o item de catálogo.
    2. Reaja adequadamente ao tipo do item de catálogo.
    3. Processe o documento do item de catálogo de uma forma específica do cliente.
  8. Registre o carimbo de data/hora de confirmação do último item de catálogo como o novo valor do cursor.

Com esse algoritmo básico, a implementação do cliente pode criar uma visão completa de todos os pacotes disponíveis na origem do pacote. O cliente só precisa executar esse algoritmo periodicamente para estar sempre ciente das alterações mais recentes na origem do pacote.

Observação

Este é o algoritmo que nuget.org usa para manter os recursos de Metadados do pacote, Conteúdo do pacote, Pesquisa e Preenchimento automático atualizados.

Cursores dependentes

Suponha que haja dois clientes de catálogo que tenham uma dependência inerente em que a saída de um cliente dependa da saída de outro cliente.

Exemplo

Por exemplo, no nuget.org, um pacote recém-publicado não deve aparecer no recurso de pesquisa antes de aparecer no recurso de metadados do pacote. Isso ocorre porque a operação de “restauração” executada pelo cliente do NuGet oficial usa o recurso de metadados do pacote. Se um cliente descobrir um pacote usando o serviço de busca, ele poderá restaurar com êxito esse pacote usando o recurso de metadados do pacote. Em outras palavras, o recurso de pesquisa depende do recurso de metadados do pacote. Cada recurso tem um trabalho em segundo plano do cliente de catálogo atualizando esse recurso. Cada cliente tem seu próprio cursor.

Como ambos os recursos são criados a partir do catálogo, o cursor do cliente de catálogo que atualiza o recurso de pesquisa não deve ir além do cursor do cliente de catálogo de metadados do pacote.

Algoritmo

Para implementar essa restrição, basta modificar o algoritmo acima para:

  1. Buscar o valor do cursor gravado em um repositório local.
  2. Baixe e desserialize o índice do catálogo.
  3. Localize todas as páginas do catálogo com um carimbo de data/hora de confirmação maior que o cursor e menor ou igual ao cursor da dependência.
  4. Declare uma lista vazia de itens de catálogo a serem processados.
  5. Para cada página de catálogo correspondente na etapa 3:
    1. Baixe e desserialize a página do catálogo.
    2. Localize todos os itens de catálogo com um carimbo de data/hora de confirmação maior que o cursor e menor ou igual ao cursor da dependência.
    3. Adicione todos os itens de catálogo correspondentes à lista declarada na etapa 4.
  6. Classifique a lista de itens de catálogo por carimbo de data/hora de confirmação.
  7. Processe cada item do catálogo em sequência:
    1. Baixe e desserialize o item de catálogo.
    2. Reaja adequadamente ao tipo do item de catálogo.
    3. Processe o documento do item de catálogo de uma forma específica do cliente.
  8. Registre o carimbo de data/hora de confirmação do último item de catálogo como o novo valor do cursor.

Usando esse algoritmo modificado, você pode construir um sistema de clientes de catálogo dependentes, todos produzindo seus próprios índices específicos, artefatos, etc.