Partilhar via

Protocolos nuget.org

  • Artigo

Para interagir com o nuget.org, os clientes precisam seguir determinados protocolos. Como esses protocolos continuam evoluindo, os clientes devem identificar a versão do protocolo que usam ao chamar APIs do nuget.org específicas. Isso permite que nuget.org introduza mudanças de forma ininterrupta para os clientes antigos.

Observação

As APIs documentadas nesta página são específicas do nuget.org e não há expectativa de que outras implementações de servidor do NuGet introduzam essas APIs.

Para obter informações sobre a API do NuGet implementada amplamente em todo o ecossistema do NuGet, consulte a visão geral da API.

Este tópico lista vários protocolos à medida que eles passam a existir.

Protocolo do NuGet versão 4.1.0

O protocolo 4.1.0 especifica o uso de chaves de escopo de verificação para interagir com serviços diferentes de nuget.org, para validar um pacote em uma conta do nuget.org. Observe que o número de versão 4.1.0 é uma cadeia de caracteres opaca, mas coincide com a primeira versão do cliente do NuGet oficial que deu suporte a esse protocolo.

A validação garante que as chaves de API criadas pelo usuário sejam usadas apenas no nuget.org e que outra verificação ou validação de um serviço de terceiros seja tratada por meio de chaves de escopo de verificação de uso único. Essas chaves de escopo de verificação podem ser usadas para validar se o pacote pertence a um usuário específico (conta) em nuget.org.

Requisitos para o cliente

Os clientes devem passar o seguinte cabeçalho quando fazem chamadas de API para enviar pacotes por push para nuget.org:

X-NuGet-Protocol-Version: 4.1.0

Observe que o cabeçalho X-NuGet-Client-Version tem semântica semelhante, mas é reservado para ser usado apenas pelo cliente do NuGet oficial. Clientes de terceiros devem usar o cabeçalho e o valor de X-NuGet-Protocol-Version.

O próprio protocolo de envio por push é descrito na documentação do recurso PackagePublish.

Se um cliente interage com serviços externos e precisa validar se um pacote pertence a um usuário específico (conta), ele deve usar o protocolo a seguir e usar as chaves de escopo de verificação e não as chaves de API de nuget.org.

API para solicitar uma chave de escopo de verificação

Essa API é usada para obter uma chave de escopo de verificação para um autor do nuget.org validar um pacote de propriedade dele.

POST api/v2/package/create-verification-key/{ID}/{VERSION}

Parâmetros da solicitação

Nome Em Tipo Obrigatória Observações
ID URL string sim O identificador de pacote para o qual a chave de verificação de escopo é solicitada
VERSION URL string não A versão do pacote
X-NuGet-ApiKey Cabeçalho string sim Por exemplo, X-NuGet-ApiKey: {USER_API_KEY}

Resposta

{
    "Key": "{Verify scope key from nuget.org}",
    "Expires": "{Date}"
}

API para verificar a chave de verificação de escopo

Essa API é usada para validar uma chave de escopo de verificação para o pacote de propriedade do autor nuget.org.

GET api/v2/verifykey/{ID}/{VERSION}

Parâmetros da solicitação

Nome Em Tipo Obrigatória Observações
ID URL string sim O identificador de pacote para o qual a chave de verificação de escopo é solicitada
VERSION URL string não A versão do pacote
X-NuGet-ApiKey Cabeçalho string sim Por exemplo, X-NuGet-ApiKey: {VERIFY_SCOPE_KEY}

Observação

Essa chave de API de escopo de verificação expira em um dia ou no primeiro uso, o que ocorrer primeiro.

Resposta

Código do Status Significado
200 A chave de API é válida
403 A chave de API é inválida ou não está autorizada a enviar por push do pacote
404 O pacote referido por ID e VERSION (opcional) não existe