APIs REST

Para acessar links de referência da API do Oracle Cloud Infrastructure e uma lista de pontos finais regionais das APIs, consulte Referência e Pontos Finais das APIs.

O caminho base do ponto final inclui a versão da API desejada (por exemplo, 20160918). Este é um exemplo de solicitação POST para criar uma nova VCN na região Ashburn:

POST https://iaas.us-ashburn-1.oraclecloud.com/20160918/vcns

O Oracle Cloud Infrastructure fornecerá um aviso prévio de 12 meses antes da data de remoção ou alteração de uma API existente de um Serviço de Nuvem que você implantou que exigiria atualização de código.

Para obter mais informações, consulte a Seção 6.3 na Documento Pilar dos Serviços de Nuvem Pública Oracle PaaS e IaaS.

Todas as solicitações da API do Oracle Cloud Infrastructure devem ser assinadas para fins de autenticação. Para obter informações sobre as credenciais necessárias e sobre como assinar as solicitações, consulte Assinaturas das Solicitações.

Todas as solicitações da API do Oracle Cloud Infrastructure devem suportar HTTPS, SSL e o protocolo TLS 1.2.

As APIs do Oracle Cloud Infrastructure usam solicitações e respostas HTTP padrão. Cada uma pode conter cabeçalhos específicos da Oracle para paginação, tags de entidade (ETags) etc., conforme descrito em outro tópico e na documentação da API.

Cada resposta inclui um ID de solicitação designado à Oracle exclusivo (por exemplo, bb3f3275-f356-462a-93c4-bf40fb82bb02) no cabeçalho de resposta opc-request-id. Se você precisar entrar em contato com a Oracle sobre uma solicitação específica, forneça este ID da solicitação.

Muitas das operações da API requerem JSON no corpo da solicitação ou retornam JSON no corpo da resposta. O conteúdo específico do formato JSON é descrito na documentação da API para a operação individual. Observe que o formato JSON não é encapsulado nem rotulado de acordo com o nome da operação ou com o tipo ou o nome do objeto.

POST https://iaas.us-phoenix-1.oraclecloud.com/20160918/vcns
host: iaas.us-phoenix-1.oraclecloud.com
opc-retry-token: 239787fs987
Content-Type: application/json
HTTP headers required for authentication
Other HTTP request headers per the HTTP spec

{
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq",
  "displayName": "Apex Virtual Cloud Network",
  "cidrBlock": "172.16.0.0/16"
}

200 OK
opc-request-id: 6c4d01a6-f764-4325-a3f8-720c8b5cae7b

{
   "id": "ocid1.vcn.oc1.phx.aaaaaaaa4ex5pqjtkjhdb4h4gcnko7vx5uto5puj5noa5awznsqpwjt3pqyq",
   "compartmentId": "ocid1.compartment.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq",
   "displayName": "Apex Virtual Cloud Network",
   "cidrBlock": "172.16.0.0/16"
   "defaultRouteTableId": "ocid1.routetable.oc1.phx.aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq",
   "defaultSecurityListId": "ocid1.securitylist.oc1.phx.aaaaaaaac6h4ckr3ncbxmvwinfvzxjbr7owu5hfzbvtu33kfe7hgscs5fjaq"
   "defaultDhcpOptionsId": "ocid1.dhcpoptions.oc1.phx.aaaaaaaawglzn7s5sogyfznl25a4vxgu76c2hrgvzcd3psn6vcx33lzmu2xa"
   "state": "PROVISIONING",
   "timeCreated": "2016-07-22T17:43:01.389+0000"
}		

Se uma solicitação resultar em erro, a resposta conterá um código de resposta HTTP padrão com 4xx para erros do cliente e 5xx para erros do servidor. O corpo também inclui JSON com um código de erro e uma descrição do erro. Por exemplo:

{
    "code": "InvalidParameter",
    "message": "Description may not be empty; description size must be between 1 and 400"
}

Para obter uma lista de erros comuns entre todos os serviços, consulte Erros da API.

O Oracle Cloud Infrastructure aplica o throttling a muitas solicitações da API para impedir o uso acidental ou abusivo de recursos. Se você fizer muitas solicitações muito rapidamente, talvez veja algumas solicitações bem-sucedidas e outras falhas. A Oracle recomenda que você implemente um backoff exponencial, começando com alguns segundos e chegando a um máximo de 60 segundos. Quando uma solicitação falha por causa do throttling, o sistema retorna o código de resposta 429, além do seguinte código de erro e da seguinte descrição:

{
      "code": "TooManyRequests",
      "message": "User-rate limit exceeded."
}

A maioria dos recursos do Oracle Cloud Infrastructure, como instâncias de computação, tem ciclos de vida. Em muitos casos, você quer que o seu código aguarde até que um recurso ou uma solicitação de serviço atinja um estado específico, ou que um timeout seja excedido, antes de executar outras ações.

Você pode sondar um recurso para determinar seu estado. Por exemplo, quando você chama GetInstance, o corpo da resposta contém um recurso de instância que inclui o atributo lifecycleState. Talvez você queira que o código aguarde até que o lifecycleState da instância esteja no status RUNNING antes de continuar.

Recursos distintos utilizam diferentes períodos de tempo para a transição entre estados. Portanto, os parâmetros de frequência e duração ideais de uma estratégia de sondagem podem variar entre recursos. Os waiters de SDK do Oracle Cloud Infrastructure usam a seguinte estratégia padrão:

• Use um backoff exponencial, começando em alguns segundos e chegando a um máximo de 30 segundos entre as tentativas de sondagem.
• Faça uma sondagem de até 20 minutos e, em seguida, pare.

Para obter mais informações sobre waiters, consulte:

• Documentação dos waiters do SDK para Java
• Documentação dos waiters do SDK para Ruby

Se usar a API, você precisará do OCID da sua tenancy para assinar as solicitações (consulte Assinaturas das Solicitações). Você também precisará dele para algumas das operações da API do Serviço IAM. Um OCID é um ID do Oracle Cloud (consulte Identificadores de Recursos).

O OCID da tenancy tem uma aparência semelhante a esta (observe a palavra "tenancy"): ocid1.tenancy.oc1..<unique_ID>.

A maioria das operações de Lista pagina os resultados. Por exemplo, os resultados são paginados para a operação ListInstances na API de Serviços Básicos. Quando você chama uma operação de Lista paginada, a resposta indica mais páginas de resultados incluindo o cabeçalho opc-next-page.

A paginação da lista do Object Storage ListObjects funciona de forma diferente porque os controles de paginação também são usados para filtragem de nome de objeto. ListObjects retorna nextStartWith em vez de opc-next-page no corpo da resposta. Para paginar mais objetos, use o valor nextStartWith retornado com o parâmetro start. Para filtrar quais objetos ListObjects retorna, use os parâmetros start e end.

Para algumas operações, você pode fornecer um token exclusivo de nova tentativa (opc-retry-token) para que haja uma nova tentativa de solicitação em caso de timeout ou de erro do servidor, sem o risco de executar essa mesma ação novamente. O token expira após 24 horas, mas pode ser invalidado antes em decorrência de operações conflitantes (por exemplo, se um recurso tiver sido excluído e expurgado do sistema, uma nova tentativa da solicitação de criação original poderá ser rejeitada).

A API suporta etags para fins de controle de concorrência otimista. As chamadas GET e POST retornam um cabeçalho de resposta etag com um valor que você deve armazenar. Quando quiser atualizar ou excluir o recurso posteriormente, defina o cabeçalho if-match para o ETag que você recebeu para o recurso. O recurso será atualizado ou excluído apenas se o ETag fornecido corresponder ao valor atual do ETag desse recurso.

Se você enviar uma string vazia ("") como valor de um parâmetro opcional, a API validará o valor como normal (por exemplo, verificações em relação aos tamanhos mínimo e máximo permitidos etc.). Geralmente, o tamanho mínimo permitido é 1; portanto, um erro seria retornado. Se você não definir o valor (ele for nulo), a API não realizará a validação, e alguma outra ação poderá ocorrer. Por exemplo: se você não definir um valor para displayName ao criar um novo objeto de VCN, o serviço gerará automaticamente um valor.